Agentic Ledger

Runtime observability for AI agents — see exactly what your agent did, why it did it, and what it cost.

Website: agentic-ledger.dev

The numbers are meant to match your provider bill. If they don't, that's a bug we want.

Works with any agent framework, any LLM provider, any model gateway. Zero code changes required. Point your agent at the proxy and everything is captured automatically.

---

How it works

Agentic Ledger runs as a transparent proxy between your agent and the LLM provider. It intercepts every request and response, assigns it an action_id, stores it, and returns the upstream response unmodified. Your agent never knows the proxy is there. The full picture, with diagrams and a module map for contributors, lives in ARCHITECTURE.md.

Your Agent  →  Agentic Ledger Proxy  →  OpenAI / Anthropic / LiteLLM / any LLM
                      ↓
               SQLite or Postgres
                      ↓
               Live Dashboard + API

---

Quick Start

Step 1 — Start the proxy

Two commands, zero config, no terminal held hostage:

pip install -U agentic-ledger
agenticledger start     # runs in the background; terminal freed

agenticledger start prints the dashboard URL and gives your terminal back — closing the window doesn't stop it. agenticledger status tells you it's up and healthy, agenticledger logs shows what it's doing, agenticledger stop shuts it down. Want a config file anyway? agenticledger init writes a commented one; see Configuration for what goes in it.

Or with Docker (no Python required):

docker run -p 8000:8000 \
  -e AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com \  # optional: omit to route by call format
  -v $(pwd)/data:/data \
  ghcr.io/shekharbhardwaj/agentic-ledger:latest

The image is multi-arch (amd64/arm64), runs as a non-root user, and every release is signed with Sigstore and ships an SBOM. Hardening a shared deployment (TLS, auth keys, redaction, verification)? See the deployment guide.

Using Anthropic / Claude? Nothing to configure: with no upstream set, the proxy routes each call by its wire format, so Anthropic-style calls go to Anthropic and OpenAI-style calls go to OpenAI, side by side through one proxy. Setting an explicit upstream_url (a gateway like LiteLLM or OpenRouter, LM Studio, or a pinned provider) switches to the classic one-proxy-one-provider behavior, mismatch hints included.

Or with docker compose (SQLite by default — see docker-compose.yml):

AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com docker compose up

With uv:

uv add agentic-ledger
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com uv run python -m agenticledger.proxy

With pip:

python -m venv venv && source venv/bin/activate
pip install -U agentic-ledger
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com ./venv/bin/python -m agenticledger.proxy

Postgres? Install the extra and set AGENTICLEDGER_DSN:

pip install "agentic-ledger[postgres]"
AGENTICLEDGER_DSN=postgresql://user:password@localhost/agenticledger

Note: the Docker image uses SQLite only. For Postgres with Docker, install via pip instead.

OpenTelemetry? Install the extra and set AGENTICLEDGER_OTEL_ENDPOINT:

pip install "agentic-ledger[otel]"
AGENTICLEDGER_OTEL_ENDPOINT=http://localhost:4318

Proxy starts on http://localhost:8000. Traces are saved to agenticledger.db in the current folder (or /data/agenticledger.db in Docker).

---

Step 2 — Point your agent at the proxy

For Claude Code, BMAD, or OpenClaw, one command writes the config for you (backed up, merged, Docker-aware):

agenticledger connect claude-code    # or: bmad, openclaw

For everything else, two changes: set base_url to the proxy and add a session ID header to group calls into a run. Everything else — your API key, model, messages — stays exactly the same.

OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",  # ← proxy
    api_key="your-openai-key",
    default_headers={"x-agenticledger-session-id": "run-1"},
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Research the top 3 AI trends in 2026"}],
)

Anthropic (no upstream config needed: /v1/messages calls route to Anthropic automatically):

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:8000",  # ← proxy
    api_key="your-anthropic-key",
    default_headers={"x-agenticledger-session-id": "run-1"},
)

LiteLLM / OpenRouter / any gateway:

# Point Agentic Ledger at your gateway
AGENTICLEDGER_UPSTREAM_URL=http://localhost:4000 uv run python -m agenticledger.proxy

# Then point your agent at Agentic Ledger
client = OpenAI(base_url="http://localhost:8000/v1", ...)

---

Step 3 — Open the dashboard

http://localhost:8000

The web app updates live via WebSocket as calls come in. No refresh needed.

• Loop Lens — every loop run with status (running / flagged / complete / stopped), a cost-per-iteration chart, a block-calls button that refuses a running loop's further calls at the wall (and an allow-calls-again to lift it; the agent being blocked cannot), per-iteration breakdowns, and plain-English explanations of every flag. Pick any two runs with ⇆ to diff them side by side — cost, iterations, calls, flags, duration with signed deltas, plus a prompt drift diff showing exactly what changed in the system prompt and opening instruction between the runs.

• Sessions — every session with three views: expandable call cards (response, thinking, tool calls, cache tokens, interaction badges), a Flow DAG of agent handoffs, and a Trace waterfall with real parent links from the loop engine. Session cards say whose they are and how they're doing at a glance: team badge, red "N failed" for real errors, amber "N blocked" for budget walls, purple tiles for replays. Hover a card for one-click delete.

• Replay the whole run — the question that decides a model switch isn't "how did it handle one call?" but "would my loop have survived?" Pick a run or session, pick a destination (a local model is free), and every step re-runs with its original inputs. You get a report card, not homework: "34 / 40 moments matched", the fumbles named ("dropped the tools"), and the cost both ways. Each step is a real captured moment replayed honestly — after step one a different model would have steered a different conversation, so the ledger compares moments, not fairy tales.

• Names, pins, projects — call it "the overnight auth fix" instead of cc-73a26366, ★ pin what matters to the top, file work under a project and filter every list by it.

• Settings — the ⚙ shows what the proxy is actually running with: config file in effect, upstream, budgets, replay targets, each row labeled file / env / default. Read-only, secrets hidden.

• Replay & what-if — open any call and ↻ Replay it: pick a destination (the panel lists what your local server actually has loaded), and the exact captured prompt re-executes there — same provider, the other one, or a free local model via LM Studio; tool calls, schemas, and system prompts are translated between the Anthropic and OpenAI wire formats automatically. Works even on calls your own budget blocked — the wall can say no and you can still see what would have happened, for $0. Replays tie back to their original with ↩ Open original. The what-if box answers the cheaper question first: reprice any run or session on another model with pure math, no API calls. (Configure AGENTICLEDGER_REPLAY_API_KEY and/or the per-provider AGENTICLEDGER_REPLAY_*_KEY targets.)

• Reports — where the money goes: spend per day, model mix with latency p50/p95/p99, per-agent totals, a by-team table with each team's spend against its card's daily allowance ("who ran dry?" in one glance), and cache savings — what your prompt-cache traffic would have cost at full input rates versus what it actually cost. Errors and blocks are counted apart everywhere: red = something broke, amber = the ledger refused on purpose — a healthy wall never makes a healthy agent look sick

• Search — full-text across prompts, outputs, and agents

• Search — full-text search across all sessions by prompt, output, agent name, or user ID

---

Configuration

agenticledger init writes agenticledger.toml with every option commented. Uncomment what you need — a working setup looks like this:

[proxy]
port = 8000
upstream_url = "https://api.anthropic.com"
db = "sqlite:///agenticledger.db"

[keys]
# Prefer *_file: the file's contents are the key, so no secret lives in
# this file or your shell history (chmod 600 the key file).
api_key_file = "~/.agenticledger/api.key"       # dashboard/admin access
ingest_key_file = "~/.agenticledger/ingest.key" # closes the open relay

[budgets]
daily = 25.0          # whole-ledger daily ceiling, USD
session = 5.0         # per-session ceiling

[replay]
# Free local replay via LM Studio (any key works there):
openai_url = "http://localhost:1234"
openai_key = "lm-studio"

Three rules:

1. The file is found in this order: AGENTICLEDGER_CONFIG, then ./agenticledger.toml (the folder you start from), then ~/.agenticledger/config.toml. First match wins; the startup banner names the file in effect.
2. Anything typed in the command beats the file. Env vars override per-setting (AGENTICLEDGER_PORT=9000 agenticledger start uses 9000 for that run without touching the file) — which is also why Docker and CI setups configured by env vars are unaffected.
3. Changes apply on restart (agenticledger stop then start).

Every setting in the environment-variable reference below has a config-file home; an [env] section passes any other AGENTICLEDGER_* variable through verbatim.

---

Coding agents — Claude Code, Ralph loops & friends

Claude Code (and most coding agents) can be pointed at the proxy with a single environment variable — no headers, no code changes:

agenticledger start

export ANTHROPIC_BASE_URL=http://localhost:8000
claude

No upstream config needed: calls route to the provider matching their wire format.

Agentic Ledger fingerprints Claude Code traffic automatically: every call is tagged framework=claude-code, and instead of one undifferentiated bucket, each Claude Code session appears under its real session UUID (the same id claude --resume shows), with prompt-cache rea