AgenticLedger

<p align="left"><img src="https://raw.githubusercontent.com/ShekharBhardwaj/AgenticLedger/main/docs/raccoon.svg" alt="" width="72" height="66"></p>

# Agentic Ledger

[![CI](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/ci.yml/badge.svg)](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/ci.yml)
[![CodeQL](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/codeql.yml/badge.svg)](https://github.com/ShekharBhardwaj/AgenticLedger/actions/workflows/codeql.yml)
[![PyPI](https://img.shields.io/pypi/v/agentic-ledger)](https://pypi.org/project/agentic-ledger/)
[![Python versions](https://img.shields.io/pypi/pyversions/agentic-ledger)](https://pypi.org/project/agentic-ledger/)
[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://ghcr.io/shekharbhardwaj/agentic-ledger)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/ShekharBhardwaj/AgenticLedger/blob/main/LICENSE)
[![MCP server on Glama](https://glama.ai/mcp/servers/ShekharBhardwaj/AgenticLedger/badges/score.svg)](https://glama.ai/mcp/servers/ShekharBhardwaj/AgenticLedger)
[![BYOAIK status](https://qhfc1deef2.execute-api.us-east-1.amazonaws.com/tools/agentic-ledger/badge.svg)](https://www.byoaik.com/tools/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](https://agentic-ledger.dev)

> The numbers are meant to match your provider bill. If they don't, [that's a bug we want](https://github.com/ShekharBhardwaj/AgenticLedger/issues/new/choose).

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](https://github.com/ShekharBhardwaj/AgenticLedger/blob/main/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](https://github.com/ShekharBhardwaj/AgenticLedger/blob/main/docs/migrating.md) does the translation in two lines. Running a context compressor like Headroom? [They chain](https://github.com/ShekharBhardwaj/AgenticLedger/blob/main/docs/chaining.md).

Two commands, zero config, no terminal held hostage:

```bash
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](#configuration) for what goes in it.

Or with Docker (no Python required):
```bash
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](https://github.com/ShekharBhardwaj/AgenticLedger/blob/main/docs/deployment.md).

> **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`):
```bash
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com docker compose up
```

With `uv`:
```bash
uv add agentic-ledger
AGENTICLEDGER_UPSTREAM_URL=https://api.openai.com uv run python -m agenticledger.proxy
```

With `pip`:
```bash
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):

```bash
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:**
```python
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):
```python
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](https://github.com/ShekharBhardwaj/AgenticLedger/blob/main/docs/integrations/azure-openai.md).

**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](https://github.com/ShekharBhardwaj/AgenticLedger/blob/main/docs/integrations/bedrock.md).

**LiteLLM / OpenRouter / any gateway:**
```bash
# 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.

- **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-concern band 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 - cost, iterations, calls, flags, duration with signed deltas, plus a **prompt drift** diff showing exactly what changed in the system prompt and opening instruction between the runs.
- **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 s