Skip to content

Commit 5ef50ce

Browse files
committed
docs(antigravity): document the data source and its accuracy limits
Adds the Antigravity guide and lists the source across the READMEs, the getting-started and all-reports pages, the environment variable reference, and the VitePress sidebar. The guide states the limitations rather than leaving them implied: cost is an equivalent public API cost and never a billed amount, unnamed model ids cannot be priced, `--offline` has no Gemini rates to use, and the retry, subagent and model-comparison paths are handled by design but have not yet been exercised against real data. Antigravity was previously listed as investigated and unsupported, because it stored conversations as opaque `.pb` payloads that needed an unpublished schema. It now writes SQLite databases whose protobuf field numbers can be recovered from the descriptors in its own binary, so that entry moves to a new section recording how the blocker was resolved.
1 parent d785048 commit 5ef50ce

8 files changed

Lines changed: 183 additions & 64 deletions

File tree

‎apps/ccusage/README.md‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -61,23 +61,24 @@ npx ccusage@latest
6161

6262
ccusage reads local usage data from coding agent CLIs and turns it into daily, weekly, monthly, and session reports.
6363

64-
| Source | Focused command example |
65-
| ------------------ | ------------------------ |
66-
| Claude Code | `ccusage claude daily` |
67-
| Codex | `ccusage codex daily` |
68-
| OpenCode | `ccusage opencode daily` |
69-
| Amp | `ccusage amp daily` |
70-
| Droid | `ccusage droid daily` |
71-
| Codebuff | `ccusage codebuff daily` |
72-
| Hermes Agent | `ccusage hermes daily` |
73-
| pi-agent | `ccusage pi daily` |
74-
| Goose | `ccusage goose daily` |
75-
| OpenClaw | `ccusage openclaw daily` |
76-
| Kilo | `ccusage kilo daily` |
77-
| Kimi | `ccusage kimi daily` |
78-
| Qwen | `ccusage qwen daily` |
79-
| GitHub Copilot CLI | `ccusage copilot daily` |
80-
| Gemini CLI | `ccusage gemini daily` |
64+
| Source | Focused command example |
65+
| ------------------ | --------------------------- |
66+
| Claude Code | `ccusage claude daily` |
67+
| Codex | `ccusage codex daily` |
68+
| OpenCode | `ccusage opencode daily` |
69+
| Amp | `ccusage amp daily` |
70+
| Droid | `ccusage droid daily` |
71+
| Codebuff | `ccusage codebuff daily` |
72+
| Hermes Agent | `ccusage hermes daily` |
73+
| pi-agent | `ccusage pi daily` |
74+
| Goose | `ccusage goose daily` |
75+
| OpenClaw | `ccusage openclaw daily` |
76+
| Kilo | `ccusage kilo daily` |
77+
| Kimi | `ccusage kimi daily` |
78+
| Qwen | `ccusage qwen daily` |
79+
| GitHub Copilot CLI | `ccusage copilot daily` |
80+
| Gemini CLI | `ccusage gemini daily` |
81+
| Antigravity | `ccusage antigravity daily` |
8182

8283
Use `ccusage daily`, `ccusage weekly`, `ccusage monthly`, or `ccusage session` to include every detected source in one report.
8384

@@ -132,6 +133,7 @@ bunx ccusage kimi daily
132133
bunx ccusage qwen daily
133134
bunx ccusage copilot daily
134135
bunx ccusage gemini daily
136+
bunx ccusage antigravity daily
135137
bunx ccusage pi daily --pi-path /path/to/sessions
136138
bunx ccusage pi daily --pi-path /path/to/sessions,/archive/pi/sessions
137139

@@ -164,7 +166,7 @@ bunx ccusage monthly --compact # Compact monthly report
164166
- 📊 **Daily Report**: View token usage and costs aggregated by date
165167
- 📅 **Monthly Report**: View token usage and costs aggregated by month
166168
- 💬 **Session Report**: View usage grouped by conversation sessions
167-
- 🤖 **Unified CLI Reports**: View Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI usage from one CLI
169+
- 🤖 **Unified CLI Reports**: View Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, and Antigravity usage from one CLI
168170
- ⏰ **5-Hour Blocks Report**: Track usage within Claude's billing windows with active block monitoring
169171
- 🚀 **Statusline Integration**: Compact usage display for Claude Code status bar hooks (Beta)
170172
- 🤖 **Model Tracking**: See which models are used across supported sources

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ export default defineConfig({
8181
{ text: 'Qwen', link: '/guide/qwen/' },
8282
{ text: 'GitHub Copilot CLI', link: '/guide/copilot/' },
8383
{ text: 'Gemini CLI', link: '/guide/gemini/' },
84+
{ text: 'Antigravity', link: '/guide/antigravity/' },
8485
{ text: 'Kimi', link: '/guide/kimi/' },
8586
{ text: 'OpenClaw', link: '/guide/openclaw/' },
8687
{ text: 'Source Support Q&A', link: '/guide/source-support-qa' },

‎docs/guide/all-reports.md‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -46,23 +46,24 @@ Unified tables include an **Agent** column so you can compare sources in one vie
4646

4747
## Supported Sources
4848

49-
| Source | Namespace | Example focused view |
50-
| ------------ | ---------- | ------------------------- |
51-
| Claude Code | `claude` | `ccusage claude daily` |
52-
| Codex | `codex` | `ccusage codex daily` |
53-
| OpenCode | `opencode` | `ccusage opencode weekly` |
54-
| Amp | `amp` | `ccusage amp session` |
55-
| Droid | `droid` | `ccusage droid daily` |
56-
| Codebuff | `codebuff` | `ccusage codebuff daily` |
57-
| Hermes Agent | `hermes` | `ccusage hermes daily` |
58-
| pi-agent | `pi` | `ccusage pi monthly` |
59-
| Goose | `goose` | `ccusage goose daily` |
60-
| OpenClaw | `openclaw` | `ccusage openclaw daily` |
61-
| Kilo | `kilo` | `ccusage kilo daily` |
62-
| Kimi | `kimi` | `ccusage kimi daily` |
63-
| Qwen | `qwen` | `ccusage qwen daily` |
64-
| Copilot CLI | `copilot` | `ccusage copilot daily` |
65-
| Gemini CLI | `gemini` | `ccusage gemini daily` |
49+
| Source | Namespace | Example focused view |
50+
| ------------ | ------------- | --------------------------- |
51+
| Claude Code | `claude` | `ccusage claude daily` |
52+
| Codex | `codex` | `ccusage codex daily` |
53+
| OpenCode | `opencode` | `ccusage opencode weekly` |
54+
| Amp | `amp` | `ccusage amp session` |
55+
| Droid | `droid` | `ccusage droid daily` |
56+
| Codebuff | `codebuff` | `ccusage codebuff daily` |
57+
| Hermes Agent | `hermes` | `ccusage hermes daily` |
58+
| pi-agent | `pi` | `ccusage pi monthly` |
59+
| Goose | `goose` | `ccusage goose daily` |
60+
| OpenClaw | `openclaw` | `ccusage openclaw daily` |
61+
| Kilo | `kilo` | `ccusage kilo daily` |
62+
| Kimi | `kimi` | `ccusage kimi daily` |
63+
| Qwen | `qwen` | `ccusage qwen daily` |
64+
| Copilot CLI | `copilot` | `ccusage copilot daily` |
65+
| Antigravity | `antigravity` | `ccusage antigravity daily` |
66+
| Gemini CLI | `gemini` | `ccusage gemini daily` |
6667

6768
## When to Focus a Source
6869

‎docs/guide/antigravity/index.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Antigravity Data Source (Experimental)
2+
3+
Antigravity support is experimental. ccusage can read Antigravity CLI usage from the per-conversation SQLite databases it writes locally, opening them read-only.
4+
5+
Read the [accuracy notes](#accuracy-notes) before relying on these numbers. Antigravity stores usage as protobuf with no published schema, and some of its recording paths could not be verified against real data yet.
6+
7+
## Quick Start
8+
9+
```bash
10+
ccusage antigravity daily
11+
ccusage antigravity monthly
12+
ccusage antigravity session
13+
```
14+
15+
Antigravity is also included in unified reports when supported databases are detected:
16+
17+
```bash
18+
ccusage daily
19+
```
20+
21+
## Data Locations
22+
23+
By default, ccusage reads every conversation database under:
24+
25+
```text
26+
~/.gemini/antigravity-cli/conversations/*.db
27+
```
28+
29+
Antigravity is a Gemini-family tool, so its CLI state lives under the shared `.gemini` directory rather than a directory of its own.
30+
31+
Set `ANTIGRAVITY_DATA_DIR` when Antigravity is stored somewhere else:
32+
33+
```bash
34+
ANTIGRAVITY_DATA_DIR="/path/to/antigravity-cli" ccusage antigravity daily
35+
```
36+
37+
With `ANTIGRAVITY_DATA_DIR` set, ccusage reads:
38+
39+
```text
40+
$ANTIGRAVITY_DATA_DIR/conversations/*.db
41+
```
42+
43+
Each conversation is a separate database, and a session in these reports is one conversation.
44+
45+
## Token Mapping
46+
47+
Antigravity records one `ModelUsageStats` message per model invocation. ccusage reads:
48+
49+
| Antigravity field | ccusage field |
50+
| --------------------------------------------------- | ------------------------------------------------ |
51+
| `input_tokens` | Input tokens |
52+
| `output_tokens` | Output tokens |
53+
| `cache_write_tokens` | Cache create tokens |
54+
| `cache_read_tokens` | Cache read tokens |
55+
| `thinking_output_tokens` + `response_output_tokens` | Output tokens, when the recorded total is absent |
56+
| `response_model` | Model |
57+
58+
`input_tokens` and `cache_read_tokens` are disjoint in the source, matching how ccusage reports them, so a cache read is never also counted as input. `output_tokens` already includes thinking tokens, so reasoning is not added on top of it.
59+
60+
Usage is read from two tables per conversation. `steps` is the primary source and holds one row per invocation, including background calls. `gen_metadata` is the only place a human-readable model name appears, and it also keeps usage visible for a step Antigravity has since pruned.
61+
62+
## Cost Calculation
63+
64+
Antigravity leaves its `model_cost`, `credit_cost` and `consumed_credits` fields unset on consumer accounts, so there is no recorded cost to read. ccusage estimates cost from token counts and LiteLLM pricing for the recorded model name.
65+
66+
That figure is the equivalent public API cost, not an amount you were billed. Antigravity is quota-based, so the actual charge for this usage may well be zero.
67+
68+
`--mode display` therefore reports no cost, because there is nothing precomputed to display:
69+
70+
```bash
71+
ccusage antigravity daily --mode calculate
72+
```
73+
74+
Use `--offline` to rely on cached pricing data:
75+
76+
```bash
77+
ccusage antigravity daily --offline
78+
```
79+
80+
The embedded offline snapshot covers Anthropic and OpenAI models. Gemini rates are only available from a runtime pricing fetch, so `--offline` reports no cost for Gemini models.
81+
82+
## Accuracy Notes
83+
84+
Antigravity ships no `.proto` files, so ccusage decodes its stored blobs by protobuf field number. Those numbers were recovered from the schema descriptors embedded in the Antigravity binary rather than guessed from the data, and Antigravity has to read the same blobs back after an upgrade, so it cannot renumber a field without breaking its own persistence.
85+
86+
Within those constraints, the following limitations apply:
87+
88+
- **Unnamed models cannot be priced.** Antigravity records the model as a numeric id, and background invocations get no `gen_metadata` row to name them. These appear as `antigravity-model-<id>`, and ccusage warns that pricing is missing for them. Their tokens are still counted, so token totals stay complete while the cost total is understated.
89+
- **Cost is an estimate, never a billed amount.** See [Cost Calculation](#cost-calculation).
90+
- **Retries are handled by design but unverified.** Failed attempts consume tokens and are recorded separately from the attempt that succeeded. ccusage collects both and deduplicates on the server-assigned response id, which is correct whether or not Antigravity repeats the successful attempt in its retry list — but this has not yet been checked against a conversation that actually retried.
91+
- **Subagents and model comparisons are unverified.** Sub-conversations get their own database, so reading every database is what makes them visible, and the same response-id dedupe prevents double counting a call a parent also recorded. Neither path has been exercised against real data.
92+
- **Historical totals depend on retention.** Antigravity trims what it keeps per conversation. If it prunes rows for an older day, that day's total will shrink; ccusage can only report what is still on disk.
93+
94+
## Troubleshooting
95+
96+
If no Antigravity data appears, check that conversation databases exist under the default path or set `ANTIGRAVITY_DATA_DIR`.
97+
98+
```bash
99+
ANTIGRAVITY_DATA_DIR="/path/to/antigravity-cli" ccusage antigravity session --json
100+
```
101+
102+
## Related Guides
103+
104+
- [All Reports](/guide/all-reports) for unified multi-source reports
105+
- [Gemini CLI Data Source](/guide/gemini/) for the other Gemini-family source
106+
- [Environment Variables](/guide/environment-variables) for the full list of path overrides
107+
- [Cost Modes](/guide/cost-modes) for how `--mode` changes cost reporting

‎docs/guide/environment-variables.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ ccusage detects supported data source files from conventional locations by defau
1717
| `HERMES_HOME` | Hermes Agent | `~/.hermes` |
1818
| `PI_AGENT_DIR` | pi-agent | `~/.pi/agent/sessions` |
1919
| `GOOSE_PATH_ROOT` | Goose | Standard Goose data roots |
20+
| `ANTIGRAVITY_DATA_DIR` | Antigravity | `~/.gemini/antigravity-cli` |
2021
| `OPENCLAW_DIR` | OpenClaw | `~/.openclaw` |
2122
| `KILO_DATA_DIR` | Kilo | `~/.local/share/kilo` |
2223
| `KIMI_DATA_DIR` | Kimi | `~/.kimi`, `~/.kimi-code` |
@@ -210,7 +211,7 @@ To see which environment variables are being used:
210211

211212
```bash
212213
# Show all environment variables
213-
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|DROID|CODEBUFF|HERMES|PI_AGENT|GOOSE|OPENCLAW|KILO|KIMI|QWEN|COPILOT|GEMINI|CCUSAGE|LOG_LEVEL"
214+
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|DROID|CODEBUFF|HERMES|PI_AGENT|GOOSE|OPENCLAW|KILO|KIMI|QWEN|COPILOT|GEMINI|ANTIGRAVITY|CCUSAGE|LOG_LEVEL"
214215

215216
# Debug mode shows environment variable usage
216217
LOG_LEVEL=4 ccusage daily --debug

‎docs/guide/getting-started.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,7 @@ If ccusage shows no data, check:
176176
- OpenClaw: `${OPENCLAW_DIR:-~/.openclaw}` (also scans `~/.clawdbot`, `~/.moltbot`, `~/.moldbot`)
177177
- Qwen: `${QWEN_DATA_DIR:-~/.qwen}`
178178
- GitHub Copilot CLI: `~/.copilot/otel/*.jsonl` or `COPILOT_OTEL_FILE_EXPORTER_PATH`
179+
- Antigravity: `${ANTIGRAVITY_DATA_DIR:-~/.gemini/antigravity-cli}`
179180

180181
### Custom Data Directory
181182

@@ -196,6 +197,7 @@ export KILO_DATA_DIR="/path/to/kilo"
196197
export KIMI_DATA_DIR="/path/to/kimi"
197198
export QWEN_DATA_DIR="/path/to/qwen"
198199
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
200+
export ANTIGRAVITY_DATA_DIR="/path/to/antigravity-cli"
199201
```
200202

201203
Each source-specific path variable can also contain comma-separated directories:

‎docs/guide/index.md‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -72,28 +72,29 @@ Each data source page covers the details that only apply to that source, includi
7272

7373
ccusage reads from local coding CLI data directories:
7474

75-
| Agent | ID | Default data location |
76-
| ------------ | ---------- | ------------------------------------------------- |
77-
| Claude Code | `claude` | `~/.config/claude/projects/`, `~/.claude/` |
78-
| Codex | `codex` | `${CODEX_HOME:-~/.codex}` |
79-
| OpenCode | `opencode` | `${OPENCODE_DATA_DIR:-~/.local/share/opencode}` |
80-
| Amp | `amp` | `${AMP_DATA_DIR:-~/.local/share/amp}` |
81-
| Droid | `droid` | `${DROID_SESSIONS_DIR:-~/.factory/sessions}` |
82-
| Codebuff | `codebuff` | `${CODEBUFF_DATA_DIR:-~/.config/manicode}` |
83-
| Hermes Agent | `hermes` | `${HERMES_HOME:-~/.hermes}/state.db` |
84-
| pi-agent | `pi` | `${PI_AGENT_DIR:-~/.pi/agent/sessions}` |
85-
| Goose | `goose` | Standard Goose data roots or `GOOSE_PATH_ROOT` |
86-
| OpenClaw | `openclaw` | `${OPENCLAW_DIR:-~/.openclaw}` |
87-
| Kilo | `kilo` | `${KILO_DATA_DIR:-~/.local/share/kilo}` |
88-
| Kimi | `kimi` | `${KIMI_DATA_DIR:-~/.kimi}` (also `~/.kimi-code`) |
89-
| Qwen | `qwen` | `${QWEN_DATA_DIR:-~/.qwen}` |
90-
| Copilot CLI | `copilot` | `~/.copilot/otel/*.jsonl` |
91-
| Gemini CLI | `gemini` | `${GEMINI_DATA_DIR:-~/.gemini/tmp}` |
75+
| Agent | ID | Default data location |
76+
| ------------ | ------------- | ---------------------------------------------------- |
77+
| Claude Code | `claude` | `~/.config/claude/projects/`, `~/.claude/` |
78+
| Codex | `codex` | `${CODEX_HOME:-~/.codex}` |
79+
| OpenCode | `opencode` | `${OPENCODE_DATA_DIR:-~/.local/share/opencode}` |
80+
| Amp | `amp` | `${AMP_DATA_DIR:-~/.local/share/amp}` |
81+
| Droid | `droid` | `${DROID_SESSIONS_DIR:-~/.factory/sessions}` |
82+
| Codebuff | `codebuff` | `${CODEBUFF_DATA_DIR:-~/.config/manicode}` |
83+
| Hermes Agent | `hermes` | `${HERMES_HOME:-~/.hermes}/state.db` |
84+
| pi-agent | `pi` | `${PI_AGENT_DIR:-~/.pi/agent/sessions}` |
85+
| Goose | `goose` | Standard Goose data roots or `GOOSE_PATH_ROOT` |
86+
| OpenClaw | `openclaw` | `${OPENCLAW_DIR:-~/.openclaw}` |
87+
| Kilo | `kilo` | `${KILO_DATA_DIR:-~/.local/share/kilo}` |
88+
| Kimi | `kimi` | `${KIMI_DATA_DIR:-~/.kimi}` (also `~/.kimi-code`) |
89+
| Qwen | `qwen` | `${QWEN_DATA_DIR:-~/.qwen}` |
90+
| Copilot CLI | `copilot` | `~/.copilot/otel/*.jsonl` |
91+
| Antigravity | `antigravity` | `${ANTIGRAVITY_DATA_DIR:-~/.gemini/antigravity-cli}` |
92+
| Gemini CLI | `gemini` | `${GEMINI_DATA_DIR:-~/.gemini/tmp}` |
9293

9394
The tool automatically detects available data and aggregates all supported coding CLIs by default.
9495
Each source-specific environment variable can also contain comma-separated directories, which lets unified reports combine current profiles and archives.
9596

96-
Some coding agents have been investigated but are not supported because their local files do not contain reliable token usage. See [Source Support Q&A](/guide/source-support-qa) for the current notes on Antigravity CLI, Grok CLI, and Devin CLI.
97+
Some coding agents have been investigated but are not supported because their local files do not contain reliable token usage. See [Source Support Q&A](/guide/source-support-qa) for the current notes on Grok CLI and Devin CLI.
9798

9899
## Report Shape
99100

0 commit comments

Comments
 (0)