Skip to content

Commit 2801bc7

Browse files
author
Aaron
committed
docs(zcode): clarify source behavior
1 parent 02a2b34 commit 2801bc7

6 files changed

Lines changed: 21 additions & 19 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ export default defineConfig({
8484
{ text: 'Kimi', link: '/guide/kimi/' },
8585
{ text: 'OpenClaw', link: '/guide/openclaw/' },
8686
{ text: 'Grok Build CLI', link: '/guide/grok/' },
87-
{ text: 'ZCode', link: '/guide/zcode/' },
87+
{ text: 'ZCode', link: '/guide/zcode/' },
8888
{ text: 'Source Support Q&A', link: '/guide/source-support-qa' },
8989
],
9090
},

‎docs/guide/claude/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ export CLAUDE_CONFIG_DIR="~/.config/claude,/backup/claude-archive"
7575
ccusage claude monthly
7676
```
7777

78-
For Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI data locations, use the source-specific environment variables listed in [Environment Variables](/guide/environment-variables).
78+
For Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Grok Build CLI, and ZCode data locations, use the source-specific environment variables listed in [Environment Variables](/guide/environment-variables).
7979

8080
### Directory Detection
8181

‎docs/guide/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ For individual developers working on multiple projects:
109109

110110
### Multiple Sources
111111

112-
Configure Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI separately with data source namespaces:
112+
Configure Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Grok Build CLI, and ZCode separately with data source namespaces:
113113

114114
```json
115115
// ~/.config/claude/ccusage.json

‎docs/guide/zcode/index.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Most users can start with unified reports such as `ccusage daily`. Add the `zcod
1919

2020
## Data Source
2121

22-
The CLI reads completed model requests from the `model_usage` table in ZCode's SQLite database, joining `session` for the project directory and app version.
22+
The CLI reads completed model requests from the `model_usage` table in ZCode's SQLite database, joining `session` for the project directory.
2323

2424
Root resolution (highest first):
2525

@@ -47,14 +47,14 @@ Only rows with `status = 'completed'` are counted. Error and cancelled attempts
4747
| `ccusage zcode monthly` | Aggregate usage by month | [Monthly Usage](/guide/monthly-reports) |
4848
| `ccusage zcode session` | Group usage by ZCode session | [Session Usage](/guide/session-reports) |
4949

50-
These views support `--json`, `--compact`, `--mode`, and `--offline`.
50+
These views support [`--json`](/guide/json-output), `--compact`, `--mode`, and `--offline`.
5151

5252
## What Gets Calculated
5353

54-
- **Token usage** - ZCode records OpenAI-style usage where `input_tokens` includes the cache-read slice. ccusage carves `cache_read_input_tokens` out of input so cache reads are reported and priced at their own rate.
54+
- **Token usage** - ZCode records OpenAI-style usage where `input_tokens` includes cache-read and cache-creation tokens. ccusage carves both cache slices out of input so the reported buckets remain additive and use their own pricing rates.
5555
- **Reasoning tokens** - ZCode's schema has a `reasoning_tokens` column, but every observed row records zero; reasoning is assumed to sit inside output and is never added on top. If a future ZCode version moves it outside, the recorded total grows past the counted buckets and ccusage routes the difference into its extra-tokens bucket instead of dropping it.
56-
- **Costs** - ZCode records no per-request cost, so every cost mode derives from the pricing tables. Model ids are lowercased for lookup (`GLM-5.3` matches the `glm-5.3` pricing entry).
57-
- **Session metadata** - Session reports carry the project directory, first/last activity, and app version from the `session` table.
56+
- **Costs** - ZCode records no per-request cost. The default `auto` mode and `calculate` estimate costs from the pricing tables; `display` shows `$0.00` because there is no recorded cost to display. Pricing lookup honors an exact raw-model override first, then tries provider-qualified Z.ai and normalized aliases.
57+
- **Session metadata** - Session reports carry the project directory and first/last activity.
5858

5959
## Environment Variables
6060

@@ -89,5 +89,5 @@ Ensure `~/.zcode/cli/db/db.sqlite` exists and has completed rows in `model_usage
8989
:::
9090

9191
::: details Costs showing as $0.00
92-
ZCode subscription usage has no recorded per-request cost, so costs are always table estimates. If a model is missing from pricing, the cost stays at zero and a missing-pricing warning may appear.
92+
ZCode records no per-request cost, so `--mode display` shows `$0.00`. Use the default `auto` mode or `--mode calculate` to estimate costs from the pricing tables. If a model is missing from pricing, the estimate stays at zero and a missing-pricing warning may appear.
9393
:::

‎docs/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ layout: home
44
hero:
55
name: ccusage
66
text: Coding (Agent) CLI Usage Analysis
7-
tagline: A fast local CLI for tracking tokens and estimated costs across Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI
7+
tagline: A fast local CLI for tracking tokens and estimated costs across Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Grok Build CLI, and ZCode
88
image:
99
src: /logo.svg
1010
alt: ccusage logo
@@ -27,7 +27,7 @@ features:
2727
link: /guide/getting-started
2828
- icon: 📁
2929
title: Local Data Sources
30-
details: Reads local usage logs from Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI without uploading your data
30+
details: Reads local usage logs from Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Grok Build CLI, and ZCode without uploading your data
3131
link: /guide/
3232
- icon: 💰
3333
title: Cost Analysis

‎rust/adapters/zcode/README.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,15 @@ Anything that is not specific to this source belongs in `ccusage-core` or
1919

2020
The `model_usage` table records one row per model request. The adapter selects
2121
rows with `status = 'completed'` — error and cancelled attempts record zero
22-
tokens — and joins `session` for the project directory and app version.
22+
tokens — and joins `session` for the project directory.
2323

2424
## Token semantics
2525

26-
- `input_tokens` **includes** the cache-read slice: the schema's own
26+
- `input_tokens` **includes** the cache-read and cache-creation slices: the schema's own
2727
`computed_total_tokens` is `input_tokens + output_tokens` exactly, and
28-
`cache_read_input_tokens <= input_tokens` holds for every observed row. The
29-
parser carves the cache-read slice out of input so the reported buckets stay
30-
additive and cache reads price at their cheaper rate.
28+
the cache buckets fit within `input_tokens` for every observed row. The parser
29+
carves both slices out of input so the reported buckets stay additive and
30+
cache tokens price at their cheaper rates.
3131
- `reasoning_tokens` and `cache_creation_input_tokens` exist in the schema but
3232
are zero in every observed row. Reasoning is assumed to sit inside output
3333
(matching how the GLM provider reports it); if a future version moves
@@ -37,9 +37,11 @@ tokens — and joins `session` for the project directory and app version.
3737

3838
## Cost semantics
3939

40-
ZCode records no per-request cost, so every cost mode derives from the pricing
41-
tables. Model ids are lowercased before lookup (`GLM-5.3` -> `glm-5.3`) because
42-
pricing keys match case-sensitively.
40+
ZCode records no per-request cost. The default `auto` mode and `calculate`
41+
estimate costs from the pricing tables; `display` reports zero because there is
42+
no recorded cost to display. Pricing lookup tries the raw model id first, then a
43+
provider-qualified Z.ai id and normalized aliases, so exact custom-provider
44+
overrides and Z.ai pricing both work.
4345

4446
## Schema stability
4547

0 commit comments

Comments
 (0)