Agentic Ledger

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

Coming from Helicone or LangSmith? The migration page does the translation in two lines. Running a context compressor like Headroom? They chain.

Two commands, zero config, no terminal held hostage:

uv tool install agentic-ledger    # or: pipx install agentic-ledger, or pip install -U agentic-ledger

agenticledger start # runs in the background; terminal freed

A tool-managed install (uv tool / pipx) gets its own isolated environment and one unambiguous shim on PATH, so shadowing by another Python's copy becomes rare and doctor-detectable, and agenticledger upgrade always means exactly one thing. Plain pip works too; if a machine ever grows competing installs, agenticledger doctor --fix untangles them.

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

For Postgres, layer the override; it swaps the DSN and adds the database service, and the image ships the driver:

docker compose -f docker-compose.yml -f docker-compose.postgres.yml 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:

`bash

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:

`bash

pip install "agentic-ledger[otel]"

AGENTICLEDGER_OTEL_ENDPOINT=http://localhost:4318

`

Proxy starts on http://localhost:8000. Traces are saved to ~/.agenticledger/agenticledger.db when started with agenticledger start (one home for the background service, wherever you launched it from), to agenticledger.db in the current folder when run in the foreground (agenticledger serve / python -m agenticledger.proxy), or to /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"}, )

Azure OpenAI: point AzureOpenAI(azure_endpoint="http://localhost:8000") at the ledger with your resource set as the upstream; deployments are priced from the model the response names. See the Azure guide.

AWS Bedrock: install agentic-ledger[bedrock], give the ledger AWS credentials through the standard chain, and point boto3 (endpoint_url) or Claude Code (ANTHROPIC_BEDROCK_BASE_URL) at it; the ledger re-signs each call itself. Both wires are covered: InvokeModel and the modern Converse/ConverseStream APIs. See the Bedrock guide.

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.

• Website-matched design - the dashboard shares the charcoal surfaces, ice-blue accents, geometric raccoon mark, and typography of agentic-ledger.dev. Session Overview adds recorded cost, calls, token totals, and a per-call cost chart. Loop Lens pairs iteration costs with a "While you were away" timeline. Unknown call prices remain explicit; all charts use captured ledger data. Calls, Flow, Trace, replay, budget controls, and light/dark appearance remain available.
• Loop Lens - every loop run with its observed status (Running / Flagged / Completion declared / Ended / Calls blocked), one open metric strip (recorded spend, the run ceiling with an honest accounting track, model calls), Overview / Activity / Cache views, a recorded-event timeline that jumps straight to the evidence, a Block calls action that refuses a running loop's further calls at the wall (and 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: an anatomy replay first (the recorded calls played one at a time, the context pile filling to what the model read, the move going out to its tool, the result rejoining the conversation or dropped when the next call starts fresh, both runs from the same start on one scale), then cost, iterations, calls, cache reads, flags, duration with signed deltas, plus a prompt drift diff showing exactly what changed in the system prompt and opening instruction between the runs. examples/loop-anatomy/ records a Ralph loop and a ReAct loop on one task so you can present the two shapes.
• Sessions - flat, scannable rows and three views: call rows (time, model, one status, latency, cost) that expand into a four-tab inspector (Response, Tools, Prompt, Raw), a Flow DAG of agent handoffs, and a Trace waterfall with real parent links from the loop engine. Rows say whose they are at a glance: team badge, red for real failures, amber for deliberate refusals, purple for replays, and a run chip linking each session to its loop.
• 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.
• In your pocket - agenticledger share opens an https tunnel you own (via cloudflared, no account), prints the pairing link, and draws a QR in the terminal: point your phone's camera and the dashboard is in your hand, kill switch, stop all calls, and ceilings included. --wifi for a same-network link, --rotate to un-pair every device, or press Pair a device in the dashboard's ⚿ panel. Local machines never need a key; everyone else meets the auto-generated pairing key. The dashboard fits a phone: one pane at a time, a back button, prev/next arrows to flip between runs.
• The wall, fleet-wide - Stop all calls is the emergency stop for every agent at once: one button in Loop Lens (with a confirm), a banner on every pa