Skip to content

Commit 5f6410c

Browse files
authored
docs: document unsupported source investigations (#1070)
Add a Source Support Q&A page that explains the local data requirements for ccusage support and records why Antigravity CLI, Grok CLI, and Devin CLI are not currently supportable. This keeps investigated-but-unsupported sources documented without adding speculative parsers that would estimate token usage from incomplete local state.
1 parent 7e20024 commit 5f6410c

4 files changed

Lines changed: 57 additions & 0 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ export default defineConfig({
8383
{ text: 'Gemini CLI', link: '/guide/gemini/' },
8484
{ text: 'Kimi', link: '/guide/kimi/' },
8585
{ text: 'OpenClaw', link: '/guide/openclaw/' },
86+
{ text: 'Source Support Q&A', link: '/guide/source-support-qa' },
8687
],
8788
},
8889
{

‎docs/guide/all-reports.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,3 +81,4 @@ ccusage gemini session --json
8181
- [Monthly Usage](/guide/monthly-reports) - Longer-term usage trends
8282
- [Session Usage](/guide/session-reports) - Per-conversation usage
8383
- [Data Sources](/guide/#data-sources) - Supported local data formats
84+
- [Source Support Q&A](/guide/source-support-qa) - Why some investigated CLIs are not supported

‎docs/guide/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ ccusage reads from local coding CLI data directories:
9393
The tool automatically detects available data and aggregates all supported coding CLIs by default.
9494
Each source-specific environment variable can also contain comma-separated directories, which lets unified reports combine current profiles and archives.
9595

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+
9698
## Report Shape
9799

98100
Run ccusage without a source name to aggregate all detected sources:

‎docs/guide/source-support-qa.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Source Support Q&A
2+
3+
ccusage only supports a coding agent when it can read local usage records with enough information to produce accurate reports. At minimum, a source needs local timestamps, session identity, model identity, and token counts or recorded costs that can be mapped to token usage.
4+
5+
If a tool stores only prompts, transcripts, quota percentages, or opaque cloud state, ccusage does not estimate token usage from text length. That would make daily, monthly, session, and cost reports look precise while being based on guesses.
6+
7+
## What Makes a Source Supportable?
8+
9+
A source is a good fit when its local files include most of the following:
10+
11+
- Per-message or per-turn token counts
12+
- Input and output token counts, with cache and reasoning tokens when available
13+
- Model identifiers for pricing
14+
- Timestamps for date filtering and grouping
15+
- Session or conversation identifiers
16+
- Stable local file formats such as JSONL, SQLite tables, or structured telemetry exports
17+
18+
Local transcript text alone is not enough. A transcript can be useful for debugging, but it does not reveal tokenizer behavior, hidden system context, cached input, tool-call overhead, or provider-side accounting.
19+
20+
## Unsupported Sources Investigated
21+
22+
::: details Why is Antigravity CLI not supported?
23+
Antigravity CLI is separate from Gemini CLI. The Antigravity CLI binary is exposed as `agy`, and it stores state under `~/.gemini/antigravity-cli/`.
24+
25+
The current local data has conversation files such as `conversations/<conversation-id>.pb`, plus lightweight history and cache JSON files. The `.pb` files are opaque binary payloads and do not expose readable token usage, model usage, or per-turn accounting without Antigravity's private schema and storage semantics.
26+
27+
The CLI log files include operational events such as conversation creation, streaming, prompt length, auth, and model configuration messages. They do not include input, output, cache, or reasoning token counts. Quota-oriented tools can inspect remaining Antigravity quota, but quota snapshots are not the same as historical per-session token usage.
28+
29+
Because the local files do not expose the token accounting needed for ccusage reports, Antigravity CLI is not supported right now.
30+
:::
31+
32+
::: details Why is Grok CLI not supported?
33+
Grok CLI was investigated, but its local SQLite data did not contain usable token accounting. Without token counts, model usage, or recorded costs in the local database, ccusage has nothing reliable to aggregate.
34+
35+
Estimating tokens from message text would ignore provider-side context, hidden prompts, tool-call payloads, cached input, and tokenizer differences, so ccusage does not do that.
36+
:::
37+
38+
::: details Why is Devin CLI not supported?
39+
Devin CLI usage information appears to live in Devin's cloud service rather than in a local usage log that ccusage can read. The locally available data did not provide direct access to historical token usage or costs.
40+
41+
ccusage is a local, read-only analyzer. It does not scrape private cloud services or depend on undocumented authenticated APIs for user usage history. If Devin adds a local export with timestamps, sessions, models, and token counts, support can be revisited.
42+
:::
43+
44+
## Can These Be Added Later?
45+
46+
Yes. Open an issue if a tool starts writing local usage data with token counts or exposes an official export. Useful examples include:
47+
48+
- A sample redacted log file
49+
- The default data directory
50+
- A description of which fields represent input, output, cache, reasoning, model, timestamp, and session ID
51+
- Notes about whether costs are recorded or should be calculated from model pricing
52+
53+
Please do not share secrets, API keys, OAuth tokens, raw private prompts, or full conversation transcripts.

0 commit comments

Comments
 (0)