agentmeter-cli 0.3.0

Monitor quota, tokens, and gateway balances for AI coding CLIs.

AgentMeter

Lightweight quota, token, and gateway balance visibility for AI coding CLIs.

中文 · English

---

中文

AgentMeter 是一个专注于额度和用量可见性的轻量工具。它展示 Claude Code 订阅额度、Codex CLI 本地 Token，以及中转站提供的余额或套餐数据。

它不会接管请求流量，不负责模型切换，也不会保存 API Key。项目定位是状态展示和诊断，不是 CC Switch 的替代品。

能力矩阵

数据源	指标	获取方式	可信度
Claude Code	Context、5 小时、7 天额度、重置时间	Status line stdin	官方运行时数据
Codex CLI	输入、输出、缓存、推理 Token	最新本地 JSONL 会话	本地精确统计
API 中转站	余额、已用额度、总额度	用户配置的 HTTPS JSON API	取决于中转站
自定义价格	Token 成本	Token × 配置单价	本地估算

支持任何提供 JSON 余额接口的服务，包括 New API、One API、LiteLLM，以及 DeepSeek、千问、Kimi、GLM、MiniMax、火山引擎、SiliconFlow、OpenRouter 等官方或第三方网关。

中转站接口没有统一标准。本项目不会猜测接口地址、字段或价格，也不会把估算费用描述为官方账单。

状态栏示例

[Claude Sonnet] │ Context ███░░░░░░░ 32% │ Usage ██████░░░░ 61% (2h 14m)
│ Weekly ████░░░░░░ 43% (4d 08h) │ Codex 362.4K tok │ Gateway 余额 ¥86.42

PyPI 安装

pipx install agentmeter-cli
agent-meter configure
agent-meter usage

可选的 Rich 终端面板：

pipx install "agentmeter-cli[dashboard]"
agent-meter monitor

源码安装

git clone https://github.com/0xYubo/claude-statusline.git
cd claude-statusline
./install.sh

安装位置：

~/.local/share/claude-statusline/
~/.local/bin/claude-statusline
~/.local/bin/claude-usage
~/.local/bin/claude-monitor

安装程序不会修改 Claude 配置，也不会全局安装 Python 依赖。

在任意终端启动 Agent 时显示

安装 zsh 集成：

./install-shell-integration.sh
source ~/.zshrc

之后在 iTerm2、Warp、Ghostty、Terminal.app 或其他使用 zsh 的终端中直接启动：

claude
codex
gemini
qwen
opencode
aider
openclaw

Shell Hook 会在 Agent 启动前和退出后显示当前 Agent 的本地用量以及已配置的中转站余额。它不会覆盖 alias/function，也不会代理或替换原始 CLI。

• Claude：运行期间继续显示 Claude Code 原生状态栏。
• Codex：安装脚本会启用原生 TUI 状态栏，持续显示 5 小时额度、周额度、上下文余量、模型和目录；启动/退出时仍显示最新本地会话 Token。
• 其他 Agent：显示已配置的网关余额；只有增加对应本地会话适配器后才显示本地 Token。

如果 Claude 启动时还没有新鲜额度，Hook 会明确提示等待首次响应；发送一条消息后，Claude 原生状态栏会自动更新，不会静默失败。

配置 Claude Code

将 statusLine 合并到 ~/.claude/settings.json：

{
  "statusLine": {
    "type": "command",
    "command": "python3 ~/.local/share/claude-statusline/statusline.py"
  }
}

启动或重启 Claude Code，并发送一条消息。Claude Code 在收到响应后提供额度数据，多个终端会话通过原子缓存共享。

查看 Codex 用量

claude-usage

agent-meter configure 会创建 ~/.config/agent-meter/config.json，但不会覆盖已有配置；升级后的程序在新路径不存在时仍会读取旧的 ~/.config/claude-statusline/config.json。默认启用 Claude 和 Codex 本地用量。在配置中可调整：

{
  "codex": {
    "enabled": true,
    "pricing": {
      "input_per_million": 0,
      "cache_per_million": 0,
      "output_per_million": 0,
      "currency": "$"
    }
  }
}

价格保持为 0 时只展示 Token。只有配置真实模型或中转站价格后才会显示估算费用。

查询中转站余额

{
  "providers": [
    {
      "id": "company-gateway",
      "name": "Company Gateway",
      "enabled": true,
      "usage_query": {
        "url": "https://gateway.example.com/api/user/self",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer ${GATEWAY_ACCESS_TOKEN}",
          "New-Api-User": "${GATEWAY_USER_ID}"
        },
        "fields": {
          "remaining": "data.quota",
          "used": "data.used_quota"
        },
        "divisor": 500000,
        "unit": "¥",
        "timeout": 10
      }
    }
  ]
}

凭证通过环境变量传入：

export GATEWAY_ACCESS_TOKEN="..."
export GATEWAY_USER_ID="..."

安全边界：

• 远程查询必须使用 HTTPS。
• HTTP 仅允许显式配置的 localhost。
• 响应大小限制为 1 MiB。
• 不执行自定义 JavaScript、Python 或 Shell。
• 缓存不保存请求头或密钥。

Codex Skill / Plugin

仓库包含可发布的 Codex 插件：

plugins/claude-statusline/
├── .codex-plugin/plugin.json
└── skills/manage-agent-usage/
    ├── SKILL.md
    └── agents/openai.yaml

插件提供安装、配置和故障排查工作流；Python 程序仍由本仓库维护。

从 GitHub 注册并安装：

codex plugin marketplace add 0xYubo/claude-statusline --ref main
codex plugin add agent-meter@0xyubo-ai-tools

安装或更新插件后，请新建 Codex 任务，使 Skill 被重新加载。使用示例：

使用 $manage-agent-usage 帮我配置 Codex 用量和中转站余额。

可选终端面板

python3 -m pip install --user rich
claude-monitor

rich 仅用于可选面板。核心状态栏与 claude-usage 只依赖 Python 标准库。

测试

python3 -m unittest discover -s tests -v
./test_sync.sh
PYTHONPYCACHEPREFIX=/tmp/claude-statusline-pycache \
  python3 -m py_compile statusline.py usage_core.py monitor.py
bash -n install.sh wrapper.sh test_sync.sh

测试使用临时 HOME，不会修改真实 Claude 或 Codex 缓存。

项目结构

.
├── statusline.py          # Claude Code 状态栏
├── usage_core.py          # Codex 与中转站统一用量核心
├── monitor.py             # 可选 Rich 面板
├── install.sh             # 安装脚本
├── config.example.json    # 安全配置示例
├── tests/                 # 隔离测试
└── plugins/               # Codex 插件发布结构

---

English

AgentMeter is a lightweight visibility layer for AI coding CLI quotas, local token usage, and API gateway balances.

It does not proxy model traffic, switch providers, or store API keys. Its scope is deliberately limited to usage display and diagnostics.

Supported metrics

Source	Metrics	Collection	Confidence
Claude Code	Context, five-hour and seven-day quota, reset time	Status line stdin	Official runtime data
Codex CLI	Input, output, cached, and reasoning tokens	Latest local JSONL session	Exact local record
API gateway	Remaining, used, and total quota	Configured HTTPS JSON API	Gateway-reported
Custom pricing	Token cost	Tokens × configured price	Local estimate

Any service with a JSON balance endpoint can be configured, including New API, One API, LiteLLM, and official or relay endpoints for DeepSeek, Qwen, Kimi, GLM, MiniMax, Volcengine, SiliconFlow, and OpenRouter.

Install from PyPI

pipx install agentmeter-cli
agent-meter configure
agent-meter usage

Install the optional Rich dashboard with:

pipx install "agentmeter-cli[dashboard]"
agent-meter monitor

Install from source

git clone https://github.com/0xYubo/claude-statusline.git
cd claude-statusline
./install.sh

Merge this valid JSON into ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "python3 ~/.local/share/claude-statusline/statusline.py"
  }
}

The installer does not overwrite Claude settings or install global Python packages.

Show usage when an agent starts

Enable the terminal-independent zsh integration:

./install-shell-integration.sh
source ~/.zshrc

It works in iTerm2, Warp, Ghostty, Terminal.app, and any other terminal running interactive zsh. The hook displays usage before and after direct claude, codex, gemini, qwen, opencode, aider, or openclaw commands without replacing aliases, functions, or the original executables.

• Claude keeps its native in-session status line.
• Codex gets a native TUI status line with five-hour and weekly limits, context remaining, model, and directory; local JSONL token usage is still shown at launch and exit.
• Other agents show configured gateway balances; local tokens require a dedicated session adapter.

Codex and gateway usage

claude-usage

agent-meter configure creates ~/.config/agent-meter/config.json without overwriting an existing file. If the new path does not exist, upgraded installations continue to read the legacy ~/.config/claude-statusline/config.json. Claude and Codex local usage are enabled by default. Gateway credentials must be referenced through environment variables. Provider APIs are not standardized, so configure the endpoint and JSON fields documented by the provider.

Codex plugin

The repository includes a distributable Codex plugin under plugins/claude-statusline. It bundles the manage-agent-usage skill for safe installation, configuration, and diagnostics without duplicating the Python implementation.

codex plugin marketplace add 0xYubo/claude-statusline --ref main
codex plugin add agent-meter@0xyubo-ai-tools

Start a new Codex task after installation or updates so the skill is reloaded.

Security

• HTTPS is required for remote quota APIs.
• Plain HTTP is only permitted for explicit localhost endpoints.
• Secrets are resolved from environment variables.
• Responses are limited to 1 MiB.
• No arbitrary scripts are executed.
• Request headers and API keys are never cached.

Test

python3 -m unittest discover -s tests -v
./test_sync.sh
PYTHONPYCACHEPREFIX=/tmp/claude-statusline-pycache \
  python3 -m py_compile statusline.py usage_core.py monitor.py
bash -n install.sh wrapper.sh test_sync.sh

License

MIT