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.
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.
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
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.
pip install -U agentic-ledger
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com python -m agenticledger.proxy
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
Then point your agent at it:
client = OpenAI(
base_url="http://localhost:8000/v1",
default_headers={"x-agenticledger-session-id": "run-1"},
)
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
The dashboard is at http://localhost:8000
.
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.
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.
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:
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.