The complete private workflow.

npx aibill init
npx aibill
npx aibill doctor --sources

Init performs a real 30-day machine-wide Claude Code, Codex, and experimental Gemini CLI financial scan. The project where you run it owns the project-local .ai-spend-agent state directory; init preserves existing connector, audit, and spend state. The private status cache contains Claude Code and Codex aggregates—not prompts, responses, project names, transcript paths, session IDs, or credential references.

Gemini is fixture-verified and financial-only. It can contribute estimated API-equivalent value when supported chat evidence is complete; otherwise the evidence stays missing. Gemini never enters statusline, Glance, Context Health, Apply, plan, runway, or invocation evidence.

Use --plan <id> only when automatic plan detection cannot identify your subscription. A plan label does not prove remaining entitlement or billed cost.

The complete, version-matched list is always available from npx aibill --help.

npx aibill statusline install
npx aibill statusline refresh
npx aibill statusline uninstall

The optional line is installed only in Claude Code, but its cache can hold separately labeled Claude Code and Codex cohorts. Claude Code asks the runner to render about every 30 seconds; that re-reads the cache and does not rescan transcripts. Use statusline refresh or rerun init when you need fresh evidence.

• Metered mode leads with evidence-labeled dollars.
• Subscription mode leads with transcript-reported runway only; missing limits are not inferred.
• Mixed mode keeps subscribed runway and metered money separate.
• ~ means API-equivalent value. Untilded billed money requires verified provider evidence.
• Cache evidence becomes stale after five minutes and is labeled accordingly.

connect registers a local connector stub and prints the exact next command. It does not fetch billing data. Only sync-provider makes the read-only provider API request.

npx aibill connect openai
read -rsp "OpenAI Admin key: " OPENAI_ADMIN_KEY; printf "\n"
export OPENAI_ADMIN_KEY
npx aibill sync-provider   --provider openai   --auth-reference env:OPENAI_ADMIN_KEY   --start-time <unix-seconds>

OpenAI and Anthropic connectors have non-empty live verification. Cursor and GitHub Copilot connectors remain fixture-verified beta pending live-account QA. Final invoices can still include credits, discounts, taxes, or later adjustments.

npx aibill apply writes a prompt, action plan, policy draft, verification plan, and demo package under the project’s .ai-spend-agent/ directory. In local-transcript mode it freshly rereads the matching evidence. In connected-provider mode it uses receipt-bound state from the latest explicit sync and does not silently contact the provider. It changes no external system.

The prompt asks a coding agent to inspect the cited candidates, show exact changes and rollback, wait for explicit approval, and compare matched future sessions. Sample Apply is explicitly non-executable. Provider buckets or daily aggregates that cannot prove a call-level counterfactual remain reconciliation evidence, not invented savings advice.

The guided npx aibill improve command wraps this loop end to end: it records a named local self-attested approval before printing any agent handoff, reuses one command for the matched experiment, and later calculates the quality-gated before/after result. That percentage belongs to your own matched sessions — it is never a universal saving, provider-bill, or ROI claim.

Install the MCP server when an AI client should query the structured evidence on demand, or build the Glance source preview when you want a compact Mac monitor. Neither replaces the full CLI inspection and Apply workflow.