ShekharBhardwaj/AgenticLedger

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.
---
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:
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):
> 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):
For Postgres, layer the override; it swaps the DSN and adds the database service, and the image ships the driver:
With uv:
With pip:
> **Postgres?** Install the extra and set AGENTICLEDGER_DSN:
>
> Note: the Docker image uses SQLite only. For Postgres with Docker, install via pip instead.
> **OpenTelemetry?** Install the extra and set AGENTICLEDGER_OTEL_ENDPOINT:
>
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):
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:**
**Anthropic** (no upstream config needed: /v1/messages calls route to Anthropic automatically):
**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:**
---
**Step 3 - Open the dashboard**
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.