Agent Trail

English · 简体中文 · 日本語

A local AI coding agent observability dashboard for Claude Code, Codex, OpenCode, OpenClaw, and Qoder.

Track token usage, estimated cost, tool calls, subagent trees, and replay full coding-agent sessions from local JSONL / SQLite files.

🏠 camtrik.github.io/agent-trail

---

What it does

Usage overview across all your agents

A unified dashboard aggregates token consumption and estimated cost across Claude Code, OpenClaw, Codex, OpenCode, and Qoder — broken down by day, session, project, and model. At a glance you can see:

• Total tokens and estimated USD cost for any time window (today / week / all)
• Per-project and per-model breakdowns with trends over time
• Which sessions consumed the most tokens and where your budget is going
• Live activity feed as new sessions are written to disk

Everything is computed locally from the JSONL files your agents already produce.

Full session replay with tool and subagent detail

Open any session and step through every turn exactly as it happened. The replay view goes beyond raw text — it surfaces the internal structure of each assistant turn:

• Tool calls: expand any Bash, Read, Edit, Write, or custom tool invocation to see the exact input arguments and the full output the model received
• Subagent spawns: when Claude Code or OpenClaw launches a sub-agent, the dashboard renders the nested agent tree so you can trace which subtask was delegated, what instructions it received, and what it returned
• Injected context and system events: surface hidden context blocks, permission prompts, and synthetic messages that normally live between turns but shape how the model behaves
• Token accounting per turn: see input, output, cache-read, cache-write, and reasoning token counts at the turn level, not just the session level

---

Install

Option 1 — npm (recommended, any Node.js 22+)

npm install -g @camtrik/agent-trail
agent-trail

Update an existing global install:

npm update -g @camtrik/agent-trail
# Or force the latest published version:
npm install -g @camtrik/agent-trail@latest

Works across Node 22, 24, and newer — npm install resolves native modules (better-sqlite3) for your local ABI. First install takes ~30s while deps are fetched.

Runtime logs are quiet by default. For verbose diagnostics:

AGENT_TRAIL_LOG_LEVEL=debug agent-trail

Option 2 — Docker local build

git clone https://github.com/camtrik/agent-trail.git
cd agent-trail
docker compose up --build

The default Compose file builds the app locally with Node 24 inside Docker, so your host machine does not need Node.js installed.

Open http://localhost:3030.

Option 3 — Docker published image

docker compose -f docker-compose.image.yml up -d

Or run the published image directly:

docker run --rm -p 127.0.0.1:3030:3030 \
  -v "$HOME/.claude/projects:/agents/claude:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  ghcr.io/camtrik/agent-trail:latest

Open http://localhost:3030. Mount additional agent directories with -v and the matching env var (OPENCLAW_DIR, CODEX_SESSIONS_DIR, OPENCODE_DB_PATH).

Option 4 — from source

pnpm install
pnpm dev       # starts Next.js (3000) + ingest service (8078)

See docs/GETTING-STARTED.md for full setup and environment variable reference.

---

Uninstall

npm global install

npm uninstall -g @camtrik/agent-trail

Optional cleanup for the local index/config created by the packaged app:

rm -rf ~/.agent-trail

This does not delete your original Claude Code, OpenClaw, Codex, OpenCode, or Qoder session files.

Docker Compose

Stop and remove the containers:

docker compose down
# or, if you used the published-image compose file:
docker compose -f docker-compose.image.yml down

Optional cleanup for the Docker volume that stores the dashboard's SQLite index:

docker compose down -v
# or:
docker compose -f docker-compose.image.yml down -v

Optional image cleanup:

docker image rm agent-trail:local
docker image rm ghcr.io/camtrik/agent-trail:latest

---

Supported AI coding agents

Agent	Source files	Notes
Claude Code	~/.claude/projects/**/*.jsonl	Full tool-call and subagent replay
OpenClaw	~/.openclaw/agents/*/sessions/*.jsonl	Gateway live view + file ingest
Codex	~/.codex/sessions/**/*.jsonl	Parent-child session tree
OpenCode	~/.local/share/opencode/opencode.db	SQLite source
Qoder	local cache DB	Token counts (cost excluded from rollups)

---

Use cases

Agent Trail is useful if you are:

• Inspecting Claude Code tool calls, subagent trees, and injected context
• Replaying Codex, OpenCode, OpenClaw, or Qoder coding sessions turn by turn
• Tracking LLM token usage and estimated cost across multiple agents locally
• Analyzing which sessions or projects consumed the most tokens
• Debugging expensive or failed AI coding agent runs

---

Privacy

This is a local-only tool. No data leaves your machine.

• JSONL files are parsed and indexed into a local SQLite database (data/ingest.db).
• The dashboard is read-only — it replays recorded tool calls, never re-executes them.

---