agent-usage-desktop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-usage-desktop — AI Coding Agent Usage Query

agent-usage-desktop — AI编码代理使用情况查询

Query your AI coding agent usage data directly in conversation. Supports Claude Code, Codex CLI, OpenClaw, and OpenCode.

直接在对话中查询你的AI编码代理使用数据。支持Claude Code、Codex CLI、OpenClaw和OpenCode。

When to Use

使用场景

Activate when the user asks about:

Cost / spending / billing / how much did I spend
Token usage / consumption / input / output tokens
Model comparison / which model costs most
Session history / recent sessions / session details
API call counts
Usage trends over time
Any question involving "usage", "cost", "tokens", "spend", "sessions" related to AI coding tools

当用户询问以下内容时激活：

成本 / 支出 / 账单 / 我花费了多少
Token使用量 / 消耗 / 输入 / 输出Token
模型对比 / 哪个模型成本最高
会话历史 / 近期会话 / 会话详情
API调用次数
随时间变化的使用趋势
任何与AI编码工具相关的“使用情况”“成本”“Token”“支出”“会话”类问题

How It Works

工作原理

This skill has two backends. Always detect which one to use first.

该技能拥有两个后端，需先检测应使用哪一个。

Step 1: Detect Backend

步骤1：检测后端

Run the detection script to check if the agent-usage-desktop server is running:

bash

bash SKILL_DIR/scripts/detect.sh

Output
```
API
```
→ use API mode (Step 2a)
Output
```
LOCAL
```
→ use Local mode (Step 2b)

Where

SKILL_DIR

is the directory containing this SKILL.md file.

运行检测脚本，检查agent-usage-desktop服务器是否正在运行：

bash

bash SKILL_DIR/scripts/detect.sh

输出
```
API
```
→ 使用API模式（步骤2a）
输出
```
LOCAL
```
→ 使用本地模式（步骤2b）

其中

SKILL_DIR

是包含本SKILL.md文件的目录。

Step 2a: API Mode (preferred)

步骤2a：API模式（推荐）

Use

query-api.sh

to call the agent-usage-desktop REST API. This is faster and has accurate pricing data.

bash

bash SKILL_DIR/scripts/query-api.sh <command> [options]

Commands:

Command	Description	Key Options
`stats`	Summary: total cost, tokens, sessions, prompts, API calls	`--from` , `--to` , `--source`
`cost-by-model`	Cost breakdown per model	`--from` , `--to` , `--source`
`cost-over-time`	Cost trend over time	`--from` , `--to` , `--granularity` , `--source`
`tokens-over-time`	Token usage trend	`--from` , `--to` , `--granularity` , `--source`
`sessions`	List all sessions with cost/tokens	`--from` , `--to` , `--source`
`session-detail`	Per-model breakdown for one session	`--session-id`

Options:

```
--from YYYY-MM-DD
```
— Start date (default: today)
```
--to YYYY-MM-DD
```
— End date (default: today)
```
--source claude|codex|openclaw|opencode
```
— Filter by source (default: all)
```
--granularity 1m|30m|1h|6h|12h|1d|1w|1M
```
— Time bucket (default: 1d)
```
--session-id ID
```
— Session ID for detail query

使用

query-api.sh

调用agent-usage-desktop REST API。此模式速度更快，且拥有精准的定价数据。

bash

bash SKILL_DIR/scripts/query-api.sh <command> [options]

命令：

命令	描述	关键选项
`stats`	汇总信息：总成本、Token、会话、提示词、API调用次数	`--from` , `--to` , `--source`
`cost-by-model`	各模型成本明细	`--from` , `--to` , `--source`
`cost-over-time`	随时间变化的成本趋势	`--from` , `--to` , `--granularity` , `--source`
`tokens-over-time`	Token使用趋势	`--from` , `--to` , `--granularity` , `--source`
`sessions`	列出所有会话及对应成本/Token	`--from` , `--to` , `--source`
`session-detail`	单一会话的各模型明细	`--session-id`

选项：

```
--from YYYY-MM-DD
```
— 起始日期（默认：今日）
```
--to YYYY-MM-DD
```
— 结束日期（默认：今日）
```
--source claude|codex|openclaw|opencode
```
— 按来源过滤（默认：全部）
```
--granularity 1m|30m|1h|6h|12h|1d|1w|1M
```
— 时间粒度（默认：1d）
```
--session-id ID
```
— 用于详情查询的会话ID

Step 2b: Local Mode (fallback)

步骤2b：本地模式（备选）

Use

usage.py

to parse JSONL session files directly. No server needed, but pricing is approximate (built-in price table for common models).

bash

python3 SKILL_DIR/scripts/usage.py <command> [options]

Commands:

Command	Description
`stats`	Summary totals
`cost-by-model`	Cost per model
`sessions`	Session list
`top-models`	Top N models by cost

Same

--from

--to

--source

options as API mode. Additional:

-n N

for top-models count.

使用

usage.py

直接解析JSONL会话文件。无需服务器，但定价为近似值（内置常见模型的价格表）。

bash

python3 SKILL_DIR/scripts/usage.py <command> [options]

命令：

命令	描述
`stats`	汇总总计
`cost-by-model`	各模型成本
`sessions`	会话列表
`top-models`	成本最高的N个模型

拥有与API模式相同的

--from

--to

--source

选项。额外选项：

-n N

用于指定top-models的数量。

Step 3: Interpret and Respond

步骤3：解读并响应

After getting JSON output from either backend:

Parse the JSON response
Format numbers: costs as
```
$X.XX
```
, tokens as
```
X.XK
```
or
```
X.XM
```
Answer the user's specific question — don't dump raw data
Use markdown tables for multi-row data (sessions, model breakdown)
Add brief insights when relevant (e.g., "claude-opus-4-6 accounts for 85% of your spending")

从任一后端获取JSON输出后：

解析JSON响应
格式化数字：成本格式为
```
$X.XX
```
，Token格式为
```
X.XK
```
或
```
X.XM
```
针对用户的具体问题作答——不要直接输出原始数据
多行数据（会话、模型明细）使用Markdown表格展示
相关时添加简要分析（例如："claude-opus-4-6占你总支出的85%")

Time Range Mapping

时间范围映射

Map natural language to date parameters:

User says	--from	--to
today	today's date	today's date
yesterday	yesterday	yesterday
this week	Monday of this week	today
this month	1st of this month	today
this year	Jan 1 of this year	today
last 7 days	7 days ago	today
last 30 days	30 days ago	today
last N days	N days ago	today

Calculate actual YYYY-MM-DD dates before passing to scripts.

将自然语言转换为日期参数：

用户表述	--from	--to
今天	今日日期	今日日期
昨天	昨天日期	昨天日期
本周	本周一	今日
本月	本月1日	今日
本年	本年1月1日	今日
过去7天	7天前	今日
过去30天	30天前	今日
过去N天	N天前	今日

在传入脚本前计算实际的YYYY-MM-DD格式日期。

Source Mapping

来源映射

User says	--source value
claude / claude code	claude
codex / openai codex	codex
openclaw	openclaw
opencode	opencode
all / everything / total	(omit --source)

用户表述	--source 值
claude / claude code	claude
codex / openai codex	codex
openclaw	openclaw
opencode	opencode
全部 / 所有 / 总计	（省略--source）

Examples

示例

User: "How much did I spend this month?" →

bash scripts/query-api.sh stats --from 2026-04-01 --to 2026-04-07

User: "Which model costs the most?" →

bash scripts/query-api.sh cost-by-model --from 2026-01-01 --to 2026-04-07

User: "Show me today's Claude Code sessions" →

bash scripts/query-api.sh sessions --from 2026-04-07 --to 2026-04-07 --source claude

User: "Token usage trend this week by hour" →

bash scripts/query-api.sh tokens-over-time --from 2026-04-01 --to 2026-04-07 --granularity 1h

用户："我这个月花了多少钱？" →

bash scripts/query-api.sh stats --from 2026-04-01 --to 2026-04-07

用户："哪个模型成本最高？" →

bash scripts/query-api.sh cost-by-model --from 2026-01-01 --to 2026-04-07

用户："展示我今天的Claude Code会话" →

bash scripts/query-api.sh sessions --from 2026-04-07 --to 2026-04-07 --source claude

用户："本周按小时统计的Token使用趋势" →

bash scripts/query-api.sh tokens-over-time --from 2026-04-01 --to 2026-04-07 --granularity 1h

Notes

注意事项

Local mode pricing is approximate — only common models have built-in prices
For accurate pricing, deploy the agent-usage-desktop server: https://github.com/hongshuo-wang/agent-usage-desktop

Local mode scans

~/.claude/projects

~/.codex/sessions

~/.openclaw/agents

~/.local/share/opencode/opencode.db

by default

本地模式的定价为近似值——仅常见模型内置价格
如需精准定价，请部署agent-usage-desktop服务器：https://github.com/hongshuo-wang/agent-usage-desktop

本地模式默认扫描

~/.claude/projects

~/.codex/sessions

~/.openclaw/agents

~/.local/share/opencode/opencode.db