aibill — Tilden’s free AI spend CLI
Understand your coding-agent usage before you mistake it for a bill.
Inspect Claude Code and Codex activity on your machine, see its estimated value at published API rates, and find what deserves a closer look. Add supported provider cost reports when you need billing evidence. Estimates, reported costs and missing data stay separate.
npx aibill@latest init
Free and MIT-licensed. Node.js 22+. No account or provider key is needed for the
local workflow. aibill is the short command for the same ai-spend-agent CLI.
CLI guide · Source coverage · Workspace sharing
This public repository contains the free CLI, its shared libraries, and Glance for macOS.
Use aibill on its own or with Workspace. Start with a free local review, without an account. If you already use Tilden Workspace, keep working locally and, as the Workspace owner, connect your CLI to explicitly share supported coding activity into your spending review. Connect your CLI to Workspace.
Get started
Run these from a project directory:
npx aibill@latest init # first receipt; scans supported local financial evidence
npx aibill@latest --full # inspect the evidence and its coverage
init looks back 30 days across supported local agent records on the machine.
The current project selects where project state lives; it does not limit the
scan to that project. It preserves existing connector and audit state and
seeds the private Claude Code/Codex status cache. It does not change Claude
settings or connect Workspace.
Read the basis beside each number: API-equivalent value is an estimate, not your subscription charge or invoice. A missing price or token component stays missing. If supported records are absent, the CLI says so and offers a diagnostic step; it never substitutes demo dollars.
Want to inspect the format first?
npx aibill@latest --sample # labeled illustrative data
Local analysis does not send transcripts to Tilden. The CLI can send command-count events after its first interactive notice. Disable them with
npx aibill@latest telemetry off or set AI_SPEND_NO_TELEMETRY=1 before running.
Optional sharing paths are explained in Privacy & trust.
Who it helps and what to do next
Why use this alongside provider dashboards?
Provider reports answer what that source recorded. Local transcripts help explain coding activity on your machine. aibill puts the available evidence in one local review while preserving the difference between them. It shows source, freshness and gaps so you can decide what to investigate without treating token volume as a reconciled bill.
It does not sit in the inference path, route your requests or change providers. It cannot infer a person’s billed cost, business value or productivity from activity alone.
Local estimates and provider reports
Reader validation is separate. live_verified and fixture_verified describe
how a reader or connector was exercised, not whether every number is a bill.
npx aibill@latest doctor --sources shows validation, financial evidence,
freshness and recorded errors. Permission to read a folder is not verification
of its contents.
Data sources
A model in the price table is not a connector. Planned providers are not available integrations. CLI support does not automatically enable a source in Workspace. Historical coverage depends on the source and retained records. See the generated local format reference, provider contracts and Workspace coverage.
The OpenAI CLI connector reads organization Costs and completions Usage; it does not read ChatGPT/Codex seat or subscription invoices. The Anthropic CLI connector reads Cost Report and Claude Code Analytics, not every surface in the provider’s API contract. Enterprise Analytics and third-party-hosted activity are outside those implemented endpoints. Final credits, tax, discounts and settlement remain separate from reported API costs.
Connect provider cost and usage
Provider setup is optional and separate from Workspace pairing:
npx aibill@latest connect openai
# Or: npx aibill@latest connect anthropic
connect registers a local connector and prints the next sync-provider
command. It does not fetch billing data. Review that command, supply the required
admin credential through a local environment-variable reference such as
--auth-reference env:OPENAI_ADMIN_KEY, then run the explicit sync.
The credential is used with the selected provider’s official read-only API;
it is not persisted in aibill state or sent to Workspace by this command.
Provider records are stored locally for the CLI review. They are not uploaded
by workspace push. Set up hosted provider connections separately in
Workspace. Local estimates do not become invoice line items after connecting.
Choose your next local step
Full command reference and experiment limits. The guided experiment compares matched completed Claude Code/Codex session snapshots and requires declared quality. It does not automatically optimize requests, certify outcomes or prove ROI. Ownership and GitHub outcome commands record explicitly supplied or narrowly checked evidence, not company approval routing or automated business-value measurement.
Optional Workspace connection
The CLI includes an optional client for an existing invited Workspace.
To connect, run npx aibill@latest workspace connect, complete enrollment and
sharing consent in Workspace Settings → Machines, then use
npx aibill@latest workspace push to preview and share supported activity.
The browser is needed for setup; it does not need to stay open for later pushes
while the machine’s grant and sharing consent remain valid.
Shared activity includes eligible Claude Code/Codex session and token counts and project labels where available. Raw transcripts and dollar amounts stay out of that upload; provider billing is connected separately. See the setup and sharing guide for the supported dates, data fields and recovery steps.
Privacy & trust
- Local analysis: transcript processing runs on your machine. Project state
lives in
.ai-spend-agent/; caches, trust receipts and pairing state use~/.aibill/. Saved reports remain local until you share them. - Telemetry: command-count events can begin only after a notice
was shown on an interactive run. The payload includes a random installation
ID and operational fields, not command arguments, paths, prompts, project
names, dollar amounts or email. Events can be linked to the same installation.
npx aibill@latest telemetryshows the exact last payload;telemetry offorAI_SPEND_NO_TELEMETRY=1disables it. See the full disclosure. - Provider sync: an explicit read uses the local environment credential reference with that provider. aibill never sits in the inference path and never stores, prints, or proxies provider credentials.
- Workspace: pairing is optional; each explicit push requires consent to the outgoing facts. Project labels may be shared. Device credentials stay in private local pairing state. Disconnect revokes future machine access; previously accepted records follow hosted retention rules.
- Other explicit network actions:
outcome githubasks the installedghCLI for merged-PR evidence. The optional signup command sends the displayed email/ref payload only after confirmation. Normal HTTP metadata accompanies network requests. See Tilden’s privacy policy.
Contribute or build from source
git clone https://github.com/futurastudio/ai-spend-agent
cd ai-spend-agent
npm ci
npm run build
node packages/cli/dist/index.js --help
Read CONTRIBUTING.md for checks and synthetic-fixture rules. Report a bug or source request without private transcripts or credentials. Developers integrating the evidence engine can use the supported library preview.
License
MIT © Futura Studio LLC