# Agentic Ledger

Agentic Ledger is an open-source (MIT), local-first flight recorder and control plane for AI agents. It runs as a transparent proxy between an agent and its LLM provider: point the agent's base URL at it and every call is captured with full prompts, tool calls, tokens, latency, and accurate cost, including prompt-cache reads and writes (the majority of a coding agent's real spend). Everything stays on the user's machine in SQLite (Postgres supported). No signup, no cloud, no telemetry. Current release: v0.3.0-beta.1.

## Audience
Developers who run AI coding agents (Claude Code, Codex CLI, agent frameworks).

## Links
- Project repository: https://github.com/ShekharBhardwaj/AgenticLedger
- PyPI package: https://pypi.org/project/agentic-ledger/
- Website: https://agentic-ledger.dev/
- Integrations index: https://agentic-ledger.dev/integrations
- Releases: https://github.com/ShekharBhardwaj/AgenticLedger/releases
- Report an issue: https://github.com/ShekharBhardwaj/AgenticLedger/issues

## Install
pip install agentic-ledger

## Quickstart
1. Start the proxy: AGENTLEDGER_UPSTREAM_URL=https://api.anthropic.com python -m agentledger.proxy
2. Point your agent at it: export ANTHROPIC_BASE_URL=http://localhost:8000
3. Open the dashboard: http://localhost:8000
Docker image: ghcr.io/shekharbhardwaj/agentledger

## Capabilities
- Transparent proxy via base URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL); works with any framework, provider, or gateway.
- Cache-aware cost accounting per provider convention.
- Loop Lens: cost per iteration, stuck-loop detection with plain-English flag explanations, a circuit breaker that stops runaway loops, a completion promise that flips a run to complete, and a morning-report webhook.
- Hard budgets: dollar caps enforced in the request path, HTTP 429 before the call reaches the provider.
- Claude Code native: automatic session IDs, framework tags, correct cache-token pricing — one env var, nothing else.
- Flow and Trace views: an agent handoff DAG and a waterfall timeline built from real parent links.
- OpenTelemetry ingest (OTLP): Gemini CLI, Codex CLI, AutoGen, Pydantic AI, Vercel AI SDK.
- MCP built in: agents can query their own ledger (session cost, loop status, last iteration).
- Governance: PII redaction, capture levels, retention windows, audit log, integrity-tagged compliance exports.

## Supported integrations
Claude Code (base URL), Codex CLI (base URL or OTel), opencode (base URL), OpenClaw (provider baseUrl override, per-agent attribution, hard spend caps), BMAD-METHOD (personas auto-detected: sm, dev, qa, architect and more), LangGraph / CrewAI / OpenAI Agents SDK (client base_url), Gemini CLI (OTLP), AutoGen/AG2 (OTLP), Pydantic AI (either), Vercel AI SDK (OTLP), LiteLLM and OpenRouter (as upstream gateway).

## License
MIT