Track your agent-host usage

Usage reports & leaderboards#

agent-connector usage scans each agent host's own native session logs/DBs read-only and shows token usage aggregated by agent host, model, project, session, or day — as a report, a leaderboard, or an export.

Run it#

Group with --by platform|project|session|model|day, scope a window with --since 7d, restrict to one host with --platform <id>, and add --json for machine-readable output. usage leaderboard --by platform ranks hosts with the columns RANK / PLATFORM / IN / OUT / CACHE_R / CACHE_W / REASON / TOTAL / SESS / CONF (use --by model to rank by model instead). usage export --format csv|json --out <file> writes the raw aggregate rows.

terminal
text
$ agent-connector usage report --by platform --since 7d

PLATFORM       IN       OUT      CACHE_R   CACHE_W   REASON      TOTAL     SESS      CONF
----------------------------------------------------------------------------------------------
claude-code    4.10M    0.62M    8.40M     1.10M     0.31M       14.53M    132       host-reported
codex          1.22M    0.18M    0.00      0.00      0.04M       1.44M     41        host-reported
gemini-cli     0.88M    0.21M    0.00      0.00      0.00        1.09M     27        host-reported
kiro           0.34M    0.09M    0.00      0.00      0.00        0.43M     12        host-estimated
----------------------------------------------------------------------------------------------
skipped: cursor, antigravity, antigravity-cli, trae, warp (requires sync — no local cache found)

# totals are WHOLE-CONVERSATION per agent host — NOT per-MCP or per-tool.
# agent hosts don't log per-tool token attribution, so usage cannot itemize it.

Per-MCP (serve-proxy) vs connector-free (host-scan)#

What usage does NOT show: per-MCP / per-tool cost

This is the canonical explanation of the two telemetry sources — the rest of the docs link here. The connector-free usage host-scan reports whole-conversation totals per agent CLI / model / project / session / day — it does not itemize cost per individual MCP server or per tool. Agent CLIs fold tool results into the session's input tokens and never attribute them to a tool name, so the connector-free path can only report whole-conversation totals. This is a current capability boundary of host logs. Per-MCP and per-tool token costs require the MCP to run through agent-connector's serve proxy, which is the MCP-developer telemetry track — and even then only for a server your own connector declares and wraps, not for an arbitrary MCP you didn't author.

See the CLI reference for every usage flag. usage is the only token view that works with no setup — the unified leaderboard's other two boards need a connector or the opt-in usage hook.