Docs

Everything Agent Ledger does, and how it gets its numbers.

Getting started

You need Node.js 20 or newer. Then run:

npx agent-ledger

Agent Ledger reads your logs (usually a second or two the first time, much less after that), starts a local server on http://127.0.0.1:4545 (or the next free port) and opens your browser. Press Ctrl+C in the terminal to stop it.

To install it permanently: npm install -g agent-ledger, then run agent-ledger.

Using the dashboard

• Period and tool: the two menus at the top. Your choice is remembered, and it's in the URL, so the browser's Back button works.
• Bill summary: the API-equivalent cost for the period, tokens (with the share served from cache), sessions, active time and the time-saved estimate.
• Spend per day: stacked by project. Hover a column for the breakdown. Long periods switch to weekly or monthly columns.
• Projects: select a row to scope the whole dashboard to that project. Export CSV downloads the table for the period.
• Most expensive sessions: session titles come from the tool (Claude Code's own title, otherwise your first prompt). Costs are whole-session totals, including sub-agents.
• Budgets: daily and monthly limits across all tools (Edit opens Settings), and a monthly limit per project, set on the project's page. You get a desktop notification at 80% and 100%.
• Project page: Rename gives a folder a readable name. Merge into… folds this folder into another project (for an old clone or a worktree); Undo appears right after, and Unmerge stays on the target project's page.
• Settings: your plan fees, budgets, your coding pace for the time-saved estimate, prices for any model Agent Ledger doesn't know, and the optional encrypted backup.

While the tab is open the dashboard re-reads changed logs every minute. The refresh button does it immediately.

Terminal report

agent-ledger report                       # last 30 days by project
agent-ledger report --since month --by model
agent-ledger report --since 2026-09-01 --until 2026-09-15 --tool codex
agent-ledger report --since all --by day --json

agent-ledger update-prices downloads the latest public price list.

Where logs are read from

How costs are calculated

Every model request in the logs records its token counts. Agent Ledger prices each request separately:

• Fresh input, output, cache reads, 5-minute cache writes and 1-hour cache writes each have their own rate.
• Requests with prompts above a model's long-context threshold (200K for older Claude models, 272K for recent OpenAI models) use the higher rate, as the vendors bill them.
• Anthropic fast mode and US-only inference use the multipliers in the price list.
• Claude Code writes a streamed response several times, and only the last copy has the final output count. Agent Ledger keeps that copy. Codex logs running totals, and Agent Ledger takes the difference between consecutive totals.

Prices come from the LiteLLM public price list. A snapshot ships with Agent Ledger; Update prices fetches the current one. You can override any model's price in Settings.

The number shown is API-equivalent cost. On a subscription you pay the plan fee, not this amount. Not included: web search fees, batch discounts and negotiated rates.

How projects are grouped

Each session belongs to the folder it started in. If that folder is inside a git repository, the repository root is the project, so sessions started in my-app/packages/web count toward my-app. Agent Ledger never treats your home folder as a repository.

Active time and time saved

Active time counts the time between messages in a session. Any gap longer than 5 minutes is left out.

Time saved = lines added by the AI's file edits ÷ your pace in lines per hour (50 by default). Claude Code logs every edit it makes. Codex logs edits made through its patch tool, but not edits made through shell commands. This is an estimate, and depends entirely on the pace you set.

Data Agent Ledger stores

Agent Ledger only reads the tools' logs; it never changes them. It writes its own files here:

With a backup there are two more files here: cloud.json (sync state, and on systems without a keychain the sign-in token; never the passphrase or key) and cloud-history.json (daily totals restored from your other computers).

history.json contains token counts, timestamps, working folders and session titles parsed from your logs. It is how history survives when Claude Code deletes transcripts older than 30 days. To remove everything, delete both folders. Set AGENT_LEDGER_HOME to keep all of it in one folder of your choice.

Encrypted backup and sync (optional)

Without an account everything stays on this computer, exactly as before. Signing in backs up your settings so a new or replacement computer gets them back, and keeps two computers in step.

agent-ledger cloud login        # emailed code, then a passphrase (first computer) or your passphrase (others)
agent-ledger cloud status
agent-ledger cloud sync
agent-ledger cloud history off  # stop backing up daily totals
agent-ledger cloud logout       # this computer only; local data stays
agent-ledger cloud delete       # deletes the backup on the server

The same steps are in the dashboard under Settings → Backup and sync, which also lists your devices (and can revoke one).

• What syncs: plan fees, pace, price overrides, budgets and project renames, merges and budgets. Project keys are paths like ~/code/app, so they line up across computers with the same folder layout. Optionally, daily totals (tokens, requests, cost, active time, lines per day, tool, project and model).
• What never syncs: logs, prompts, code, session titles, history.json, logDirs, alerts.json and the price cache.
• Encryption: done on your computer before upload, with a key only your passphrase or recovery key opens. The first computer shows the recovery key once; write it down. If you lose both, the backup can't be recovered, by you or by us.
• Merging: a new computer takes the backup, except settings it already changed from the defaults. After that, each field (and each project) changed on one computer wins; changes to different fields on two computers both survive.
• Restored history: daily totals from your other computers fill the days this computer has no logs for (the dashboard footer says how many). A day with logs here uses only those, so the same logs aren't counted twice. If two computers were both used on one day, only this one's usage shows for that day. Restored costs use the prices at the time they were backed up.
• Keys: on macOS the sign-in token and unlocked key go in the Keychain. Elsewhere, the key stays in memory, so the dashboard asks for your passphrase after a restart. AGENT_LEDGER_KEYCHAIN=off turns the Keychain off.
• Your own server: --server <url> with cloud login, the Server field in Settings, or AGENT_LEDGER_CLOUD_URL.
• Anonymous stats are a separate switch in Settings (or agent-ledger cloud stats on), off by default: once a day, a random install ID, the version and an error count. See the privacy policy.

Troubleshooting

• "No AI coding logs found": the page lists the folders it checked. Point Agent Ledger at yours with --claude-dir, --codex-dir or --gemini-dir, or add them under logDirs in the config file (agent-ledger config shows where it is).
• A model shows "no price": run Update prices in Settings, or enter the price yourself (USD per million tokens). Enter 0 if it's free.
• "Can't reach Agent Ledger": the terminal process was stopped. Run npx agent-ledger again.
• Port in use: Agent Ledger tries the next free port automatically, unless you set one with --port.