ZCode Data Source

ccusage reads completed ZCode model-usage records from the local SQLite database and exposes the same focused and unified reports as the other supported sources.

Focused Views

ccusage zcode daily
ccusage zcode monthly
ccusage zcode session

Use ccusage daily, ccusage monthly, or ccusage session when ZCode should be included with every other detected source.

Data Source

ZCode stores its usage ledger at cli/db/db.sqlite beneath its data root:

$ZCODE_HOME/   # or ~/.zcode
└── cli/
    └── db/
        └── db.sqlite

Set ZCODE_HOME to one root or a comma-separated list of roots when usage data is stored elsewhere. Roots and database paths are canonicalized and deduplicated. When ZCODE_HOME is non-empty, invalid configured roots are skipped and discovery does not fall back to ~/.zcode.

The adapter validates the model_usage and session tables before reading them. The required columns are id, session_id, started_at, model_id, status, input_tokens, and output_tokens on model_usage, plus id and directory on session. Optional cache, provider, computed-total, and session version columns are detected individually. The presence of session.version is reported as the session-versioned layout; older databases without it use the legacy layout. Compatible additive schema changes are accepted, while incomplete or unrelated databases are ignored.

Only rows whose status is exactly completed are counted. started_at is an epoch-millisecond timestamp, so report dates retain sub-second precision in the source entry. The read query selects only identifiers, timestamps, status, token counters, model/provider metadata, and the session directory. Prompt, content, and raw usage fields are not materialized.

Connections are opened read-only, use a busy timeout while ZCode may be writing, and enable connection-local SQLite query-only mode. The adapter does not change journal mode, so an existing ZCode WAL remains available for concurrent reads.

Token and Cost Handling

ZCode's input_tokens includes both cache-read and cache-creation tokens. The adapter subtracts both buckets from fresh input and reports them separately. Cache buckets are bounded by the inclusive input count, and any positive remainder in computed_total_tokens is preserved by the shared extra-token fallback.

ZCode does not record a per-request cost. --mode display therefore reports zero cost. --mode calculate and auto use the shared model pricing map when the model can be resolved. Built-in Z.ai pricing is selected for an explicit Z.ai provider, or for legacy rows with no provider and a GLM model. A custom provider UUID is not treated as a billable provider even when its model name matches a generic pricing entry; use an explicit model pricing override when that provider should be estimated. Unpriced models remain at zero cost and use the standard missing-pricing warning. Z.ai cache-creation tokens remain in the displayed cache-creation bucket but are estimated at the model's standard input rate because they represent new content.

Configuration

The zcode namespace supports the shared report options:

{
	"zcode": {
		"defaults": {
			"offline": true
		},
		"commands": {
			"daily": {
				"json": true
			}
		}
	}
}

The data root is controlled by ZCODE_HOME; it is not a billing or provider configuration setting.

Report Views

Focused view	Description	See also
ccusage zcode daily	Aggregate usage by date	Daily Usage
ccusage zcode monthly	Aggregate usage by month	Monthly Usage
ccusage zcode session	Group usage by ZCode session	Session Usage

These views support the standard --json, --compact, --mode, --offline, --since, --until, and --timezone options.

Troubleshooting

No ZCode usage data found

Ensure $ZCODE_HOME/cli/db/db.sqlite or ~/.zcode/cli/db/db.sqlite exists and contains the model_usage and session tables. Use --debug to see rejected roots, schema diagnostics, and database read errors.

Costs showing as $0.00

ZCode has no per-request cost field. Use --mode calculate to estimate rows whose model is in the pricing map. Custom provider UUIDs do not identify a billable provider, so unpriced custom models remain at zero.

Totals lower than expected while ZCode is open

Only completed model-usage rows are included. Wait for the turn to complete and rerun the report.