agenttrail
Local observability map for AI coding agents. Watch Claude Code, Codex, and Cursor plans, tool calls, file changes, and progress in real time.
What is it?
What it is
agenttrail is a local, open-source observability layer for AI coding agents that turns plans, tool calls, file changes, and progress from agents like Claude Code, OpenAI Codex, and Cursor into a live project map.
Why it exists
To give developers real‑time visibility into what their coding agents are doing, showing intended work versus actual file changes so they can spot stalled or re‑opened work without accounts, telemetry, or cloud services.
Who should use it
Teams using AI coding agents like Claude Code, OpenAI Codex, or Cursor who want real-time visibility into agent activity and code changes
Who should avoid it
Users who prefer centralized logging solutions or have strict requirements for remote agent oversight beyond local observation
How it works
A quick walkthrough in plain English
How agenttrail works
Step 1 of 3
You interact with it
Open agenttrail, send a request, or connect it to your stack.
Features
Advantages
- No account, no global install, no telemetry required
- Daemon binds to 127.0.0.1 only; data never leaves your machine
- Claude Code hooks live in repo-local settings with consent-based relay
- Read-only dashboard never sends prompts or edits your code
- MIT licensed open-source software
- Works without PLAN.md for core functionality; PLAN.md enables full component map
- Handles huge repos with intelligent tree abridgement
- One daemon manages multiple boards via tab switcher
- Autostart and self-heal for repo boards at login
- Provenance pills keep agent intent separate from roadmap intent
Disadvantages
- Dashboard is read-only; cannot control or send prompts to your agent
- Full component map requires agent to write and maintain PLAN.md
- Plan can go stale; requires manual re-verification against code
- Only observes; never sends a prompt or edits your code
- Daemon is repo-local; cannot monitor remote repos without local setup
- Per-directory caps and abridged tree may omit detail in very large repos
- Richest live view for Claude Code; OpenAI Codex and Cursor have limited features
- No built-in collaboration or team-sharing features beyond single-repo daemon
- Requires Node.js >= 20 and local hook configuration for full functionality
- Static HTML interface may lack advanced interactivity of web apps
Installation
native
npx agenttrail npx agenttrail init npx agenttrail up npx agenttrail autostart
FAQ
Does agenttrail work without PLAN.md?
Yes. The live tree, activity feed, and run cards need no plan. The map appears when your agent writes one.
What does coding agent observability mean here?
LLM observability usually focuses on traces, latency, tokens, and cost. agenttrail focuses on the work happening in a repo: which component an agent is in, what tool it is running, what files it is changing, and whether its plan is moving.
Which AI coding agents does agenttrail support?
Claude Code has the richest live view through local hooks. OpenAI Codex, Cursor, and any agent that edits files work through the repo watcher and can maintain the map through AGENTS.md.
Does agenttrail control my agent?
No. It observes and draws. It never sends a prompt. `init` prints the optional backfill prompt, and the board can copy it to your clipboard.
What does `init` change?
It creates the starter plan, appends the convention to the repo's agent instruction files, adds .agenttrail/ to .gitignore, and installs local Claude Code hooks. The running dashboard itself is read only.
What about a huge repo?
agenttrail has been tested on a 78k-file repo. It reads the tree breadth first with per-directory caps, sends tiny SSE activity ticks, and tells you when the tree is abridged.
Featured in Videos
YouTube tutorials and walkthroughs for agenttrail
Alternatives
Similar projects ranked by category, topics, and text overlap.
