Metadata-Version: 2.4
Name: agentmeter-cli
Version: 0.3.0
Summary: Monitor quota, tokens, and gateway balances for AI coding CLIs.
Author: 0xYubo
License-Expression: MIT
Project-URL: Homepage, https://github.com/0xYubo/claude-statusline
Project-URL: Repository, https://github.com/0xYubo/claude-statusline
Project-URL: Issues, https://github.com/0xYubo/claude-statusline/issues
Keywords: ai-agent,claude-code,codex,quota,statusline,token-usage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dashboard
Requires-Dist: rich<15,>=13; extra == "dashboard"
Provides-Extra: publish
Requires-Dist: build<2,>=1; extra == "publish"
Requires-Dist: twine<7,>=5; extra == "publish"
Dynamic: license-file

# AgentMeter

<p align="center">
  <strong>Lightweight quota, token, and gateway balance visibility for AI coding CLIs.</strong>
</p>

<p align="center">
  <a href="https://github.com/0xYubo/claude-statusline/actions"><img alt="Tests" src="https://img.shields.io/badge/tests-unittest-2ea44f?style=flat-square"></a>
  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"></a>
  <img alt="Python 3.8+" src="https://img.shields.io/badge/python-3.8%2B-f4c430?style=flat-square&logo=python">
  <img alt="No proxy required" src="https://img.shields.io/badge/proxy-not%20required-6f42c1?style=flat-square">
</p>

<p align="center">
  <a href="#中文">中文</a> · <a href="#english">English</a>
</p>

---

## 中文

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 等官方或第三方网关。

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

### 状态栏示例

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

### PyPI 安装

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

可选的 Rich 终端面板：

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

### 源码安装

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

安装位置：

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

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

### 在任意终端启动 Agent 时显示

安装 zsh 集成：

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

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

```bash
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`：

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

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

### 查看 Codex 用量

```bash
claude-usage
```

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

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

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

### 查询中转站余额

```json
{
  "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
      }
    }
  ]
}
```

凭证通过环境变量传入：

```bash
export GATEWAY_ACCESS_TOKEN="..."
export GATEWAY_USER_ID="..."
```

安全边界：

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

### Codex Skill / Plugin

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

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

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

从 GitHub 注册并安装：

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

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

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

### 可选终端面板

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

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

### 测试

```bash
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 缓存。

### 项目结构

```text
.
├── 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

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

Install the optional Rich dashboard with:

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

### Install from source

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

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

```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:

```bash
./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

```bash
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.

```bash
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

```bash
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](LICENSE)
