Agent Ledger

Your private AI usage ledger for macOS.

Turn local Codex and Claude Code logs into clear token, model, cache, session, and API list-price trends—without uploading your work.

Website · Download · Architecture · 中文说明

---

Why Agent Ledger?

AI coding tools expose useful local usage counters, but each tool stores them differently. Agent Ledger normalizes those counters into one native macOS dashboard while keeping the surrounding context private.

• Local by design — no telemetry, account, VPN, server, or network upload module.
• Honest token accounting — separates uncached input, cache reads/writes, output, and reasoning without double counting.
• Useful cost context — estimates official API list-price equivalents and clearly marks unknown/private models.
• Fast incremental refresh — resumes from per-file byte offsets and rebuilds only logs that changed unexpectedly.
• Native and quiet — SwiftUI dashboard, menu bar glance view, launch-at-login, Apple Silicon and Intel support.

Supported sources

Source	Status	Method
Codex	Supported	Adjacent deltas from local cumulative token events
Claude Code	Supported	Final streamed usage per session/message identity
Generic JSONL inbox	Supported	Documented local import schema
Cursor	Detection only	Shown as unsupported without a verified local token schema
OpenCode	Detection only	Auth/config files are explicitly excluded
Gemini CLI	Detection only	Can use the generic inbox when structured usage is available

Agent Ledger never displays a misleading zero for a tool it cannot verify.

Privacy boundary

Stored in the private local index

• Event timestamp
• Agent and raw model name
• Mutually exclusive token counters
• API list-price estimate and catalog version
• Machine-local HMAC event, session, and file identifiers

Explicitly skipped

• Prompts and responses
• Code and tool input/output
• Working directories and project paths
• Git remotes, titles, previews, and user messages
• Authentication, settings, keys, and tokens

The app data directory is mode 0700; SQLite, WAL, SHM, and the local random salt are mode 0600. Original Agent logs are read-only and never modified.

How monitoring works

“Monitoring” means incrementally reading structured counters already written by local Agent tools. It does not use process injection, keyboard capture, screen recording, or network interception.

Local Agent JSONL
        ↓
Field-allowlist parsing
        ↓
Cumulative delta / stream deduplication
        ↓
HMAC-SHA256 local identifiers
        ↓
Private incremental SQLite index
        ↓
SwiftUI trends and API list-price estimates

Read the detailed schemas, deduplication keys, replacement handling, migrations, and pricing semantics in ARCHITECTURE.md.

Install

1. Download AgentLedger.dmg.
2. Drag Agent Ledger into Applications.
3. On the first launch, right-click the app and choose Open if macOS requests confirmation.

Current self-built releases are ad-hoc signed. A broadly distributed build should use a Developer ID signature and Apple notarization.

Build from source

Requirements: macOS 14+, Swift 5.10+, and Apple Command Line Tools.

swift build -Xswiftc -warnings-as-errors
swift run AgentLedgerSelfTest
./Scripts/build-app.sh

The packaging script creates a universal app and dist/AgentLedger.dmg for Apple Silicon and Intel Macs.

Generic JSONL inbox

Place newline-delimited usage events in ~/Library/Application Support/AgentLedger/inbox/:

{"id":"request-123","timestamp":"2026-08-12T10:30:00+08:00","agent":"my-agent","model":"gemini-2.5-pro","sessionId":"session-1","usage":{"uncachedInputTokens":1200,"cacheReadTokens":300,"cacheWriteTokens":0,"cacheWrite5mTokens":0,"cacheWrite1hTokens":0,"outputTokens":450,"reasoningOutputTokens":120}}

The supplied IDs are scoped by Agent and session, then HMACed before database insertion.

Pricing disclaimer

Costs are official standard API list-price equivalents, not subscription or enterprise bills. Cache categories are priced separately; reasoning tokens remain a subset of output. Unknown and private model names still count toward token totals but remain unpriced.

The built-in catalog was verified on 2026-08-12 against first-party OpenAI, Anthropic, and Gemini pages.

Contributing and security

See CONTRIBUTING.md before adding a data-source adapter. Report privacy or security issues through private GitHub Security Advisories as described in SECURITY.md.

中文简介

Agent Ledger 是一个完全本地的 macOS 个人 Agent 用量账本。它目前支持 Codex、Claude Code 和通用 JSONL 导入，统计 Token、缓存、输出、模型、会话和 API 列表价等价费用。

它只读取本机 Agent 已经生成的结构化计数字段，不读取或保存提示词、回复、代码、项目路径、Git 信息或凭据；不修改 Git/Agent hooks；不上传数据；不提供员工、部门、排名或远程管理功能。无法验证本地 Token 口径的工具会显示“暂不支持”，不会伪造为 0。

License

MIT © 2026 Jake Hu