AgentMeter

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

中文 · English

---

中文

AgentMeter 是一个专注于额度和用量可见性的轻量工具。它展示 Claude Code 当前供应商或真实响应模型、当前窗口 Token、官方订阅额度，以及受支持的官方供应商余额。

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

能力矩阵

数据源	指标	获取方式	可信度
Claude Code	当前供应商/模型、Context、当前窗口 Token、5 小时与 7 天额度	Status line stdin + 当前 transcript	官方运行时与本地精确记录
DeepSeek 官方	CNY/USD 账户余额	api.deepseek.com/user/balance	官方接口
Kimi For Coding	5 小时与周套餐额度	api.kimi.com/coding/v1/usages	官方服务接口
Codex CLI	输入、输出、缓存、推理 Token	最新本地 JSONL 会话	本地精确统计
API 中转站	可选的余额、已用额度、总额度	agent-meter 用户配置的 HTTPS JSON API	取决于中转站，不进入 Claude 状态栏
自定义价格	Token 成本	Token × 配置单价	本地估算

agent-meter usage 仍可配置任何提供 JSON 余额接口的服务；Claude 状态栏只主动查询严格匹配的 DeepSeek 与 Kimi For Coding 官方 HTTPS 地址，中转站和号池不显示推测余额。

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

状态栏示例

[华为] │ Context ██░░░░░░░░ 16% │ Session 68.4K tok
[deepseek-v4-pro] │ Context ███░░░░░░░ 32% │ DeepSeek 余额 ¥86.42 │ Session 24.8K tok

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 在收到响应后提供额度数据，多个终端会话通过原子缓存共享。

状态栏优先显示供应商切换后当前会话最近一次真实响应的模型 ID；尚未收到新响应或接口未返回模型时，显示 CC Switch 当前供应商名称。Session Token 按 message.id 去重统计当前窗口的完整会话，不混入其他窗口；官方余额通过 10 秒跨进程缓存共享。

• Claude 官方：显示 CLI 响应提供的 5 小时和周额度；已到达 resets_at 的窗口立即失效。
• DeepSeek 官方（api.deepseek.com）：通过官方余额接口显示账户总余额。
• Kimi For Coding 官方（api.kimi.com/coding）：通过官方用量接口显示 5 小时和周额度。
• 中转站、号池和相似域名：不查询、不显示余额，避免把代理 Token 额度误报成上游账户额度。

程序只向固定的官方 HTTPS 域名发送当前 Token，缓存中不会写入 Token。普通 Moonshot/Kimi API 目前没有接入未经公开稳定验证的余额接口，因此不会猜测余额。

查看 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 the active Claude Code provider or response model, current-window tokens, official subscription quotas, and supported official provider 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	Active provider/model, context, current-session tokens, five-hour and seven-day quota	Status line stdin + current transcript	Official runtime and exact local record
Official DeepSeek	CNY/USD account balance	api.deepseek.com/user/balance	Official API
Kimi For Coding	Five-hour and weekly plan quota	api.kimi.com/coding/v1/usages	Official service API
Codex CLI	Input, output, cached, and reasoning tokens	Latest local JSONL session	Exact local record
API gateway	Optional remaining, used, and total quota	User-configured agent-meter HTTPS JSON API	Gateway-reported; excluded from the Claude status line
Custom pricing	Token cost	Tokens × configured price	Local estimate

agent-meter usage can still query any explicitly configured JSON balance endpoint. The Claude status line only contacts exact official DeepSeek and Kimi For Coding HTTPS hosts; relays and account pools never show an inferred balance.

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.

The status line uses the latest actual response model received after the current provider was selected, falling back to the active CC Switch provider name until such a response exists. Its Session token figure deduplicates only the current window's complete transcript by message ID; official provider usage remains shared through a 10-second cache. Only exact official endpoints are queried: DeepSeek balance at api.deepseek.com and Kimi For Coding quotas at api.kimi.com/coding. Relay, pool, and lookalike hosts never receive a balance query and never show a claimed upstream balance. Tokens are never written to the cache.

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