Agentic Ledger: an open source flight recorder for AI agents (looking for testers and contributors)

I have been building an open source tool called Agentic Ledger and it just reached the point where I need more eyes on it than my own. This post is an introduction and an ask.

The problem

AI agents run unattended. They call LLMs in loops, use tools, spawn sub-agents, and spend real money, and most of that happens where you cannot see it. When an overnight coding loop burns $40 getting stuck on the same failing test, or a multi-agent crew quietly retries itself into a huge bill, you usually find out from the invoice.

The observability tools that exist mostly want you to instrument your code with an SDK, and each one speaks one framework. I wanted the opposite: something that watches everything, requires changing nothing, and keeps the data on my machine.

What it is

Agentic Ledger is a transparent proxy that sits between your agent and the LLM provider. You point your agent’s base_url at it, and it records every request and response, assigns each call an action id, works out what it cost, and passes the response through untouched. Your agent never knows it is there.

Your Agent  ->  Agentic Ledger Proxy  ->  OpenAI / Anthropic / any gateway
                       |
                SQLite or Postgres
                       |
                Live dashboard + API

Enter fullscreen mode Exit fullscreen mode

No SDK, no decorators, no monkey patching. It works with any framework and any provider because it operates at the only layer they all share: the HTTP call.

Everything is local-first. Your prompts stay in a SQLite file on your machine (or your own Postgres). MIT licensed.

Try it in two minutes

pip install -U agentic-ledger
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com python -m agenticledger.proxy

Enter fullscreen mode Exit fullscreen mode

Or with Docker (multi-arch, non-root, Sigstore-signed):

docker run -p 8000:8000 \
  -e AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com \
  -v $(pwd)/data:/data \
  ghcr.io/shekharbhardwaj/agentic-ledger:latest

Enter fullscreen mode Exit fullscreen mode

Then point your agent at it:

client = OpenAI(
    base_url="http://localhost:8000/v1",
    default_headers={"x-agenticledger-session-id": "run-1"},
)

Enter fullscreen mode Exit fullscreen mode

For coding agents like Claude Code it is even less work, one env var and zero headers:

export ANTHROPIC_BASE_URL=http://localhost:8000
claude

Enter fullscreen mode Exit fullscreen mode

The dashboard is at http://localhost:8000.

What you get

Real cost accounting. Per call, per session, per agent, per day, including prompt cache reads and writes priced with each provider’s own convention. Cache traffic is where most of a coding agent’s real spend lives, and most tools ignore it. My rule for this project: the numbers are meant to match your provider bill, and if they do not, that is a bug I want reported.

Loop awareness. This is the part I have not seen anywhere else. The proxy infers agent loops from raw traffic: it stitches ReAct-style threads together, groups fresh-context iterations (Ralph-style overnight loops) into runs, and flags the pathologies that waste money, like the same tool called with the same arguments over and over, or a step budget blowing past its limit. In block mode it acts as a circuit breaker and returns HTTP 429 to a stuck loop instead of letting it burn.

A loop runner. agenticledger run --max-iterations 50 --budget 25 -- <your agent command> re-executes your agent in a loop, attributes every call to the run, and stops on a completion promise, a budget ceiling, or the iteration cap, whichever comes first.

Budgets and rate limits. Hard USD caps per session, per agent, per day, enforced in the request path before the call reaches the provider.

An MCP server. Your agent (or Claude Desktop, or Cursor) can query the ledger about itself: list sessions, explain any call, check whether a run is over budget.

OTLP ingest. Frameworks that already emit OpenTelemetry GenAI spans can send them straight in.

There are step-by-step guides for Claude Code, Codex CLI, opencode, OpenClaw, BMAD-METHOD, LangGraph, CrewAI, OpenAI Agents SDK, Gemini CLI, AutoGen, Pydantic AI, Vercel AI SDK, LiteLLM, and OpenRouter in docs/integrations.

Where the project stands

Honest status: this is a solo project, currently at 0.4.0. The core is solid and tested (100+ tests, CI on three Python versions, signed multi-arch images with SBOMs), and I dogfood it daily against my own coding agents. What it lacks is mileage on other people’s stacks. That is exactly the gap you can help close.

The ask

If you run agents, be a tester. Point your stack at the proxy for a day and tell me what broke, what confused you, and whether the cost numbers match your provider console. Ten minutes of your traffic teaches me more than a week of my own.

If you want to contribute, there is real surface area:

• Framework guides. If your framework is not in the integrations list, or the guide for it misses something, a PR there is small and immediately useful.
• Pricing coverage. The cost table needs to keep up with new models and providers. Adding a model is a one-line change plus a test.
• Loop detection heuristics. If you have transcripts of an agent getting stuck in a way the flags miss, I want to see them. This is the most interesting open problem in the project.
• Frontend. The dashboard is a small React + Vite app. If you enjoy data-dense UI work, there is plenty to improve.
• Postgres at scale. The Postgres backend works, but has not been hammered. If you run heavier traffic, your findings are valuable.

There is a CONTRIBUTING guide in the repo, and I am seeding the issue tracker with starter tasks labeled good first issue. And if none of the above fits but you have opinions on what an agent observability tool should do, open an issue and say so. At this stage, direction feedback matters as much as code.

Repo: https://github.com/ShekharBhardwaj/AgenticLedger
Site: https://agentic-ledger.dev
Install: pip install -U agentic-ledger

Thanks for reading. Come break it.