agenttrail

agenttrail is a local, open-source observability tool for AI coding agents, created by Kelly Sun (sodiumsun on GitHub) and released under the MIT license. It runs entirely on localhost with no account, no telemetry, and no cloud dependency, making it a privacy-first option for developers who want to monitor what their coding agents are actually doing in real time.

What It Is

agenttrail sits between you and your AI coding agent — Claude Code, OpenAI Codex, Cursor, or any agent that edits files — and renders a live project map showing plans, tool calls, file changes, and progress. Instead of replaying a transcript after the fact, it shows the shape of the work as it unfolds. The core is a single dependency-free Node.js file (~470 lines) and a static HTML interface, launched with one npx command.

How the Live Agent Map Works

The tool reconciles two signals to give you an honest picture of agent activity:

• Declared: what the agent says it is working on (from PLAN.md)
• Observed: what files it is actually changing right now, including revisions to work it already marked done

When those signals disagree, the map highlights the discrepancy. A completed task card lights up when its files change again. The map moves as the work moves, with dependency arrows, dashed links, progress states (done, working, blocked), and elapsed time on active runs.

Supported Agents and Integration Depth

agenttrail supports three tiers of integration:

• Claude Code — richest view: live file watcher, run cards with task lists and streaming tool lines, and map maintenance via CLAUDE.md and local hooks stored in .claude/settings.local.json
• OpenAI Codex — file watcher and map maintenance via AGENTS.md
• Cursor and others — file watcher and map maintenance via AGENTS.md

The npx agenttrail init command bootstraps the full setup: it appends the agenttrail convention to CLAUDE.md and AGENTS.md, creates a starter PLAN.md, and installs additive local Claude Code hooks. A "Copy backfill prompt" button on the board lets you hand the agent a prompt to study the codebase and draw the component map itself.

The PLAN.md Convention

The durable map lives in a single Markdown file (PLAN.md) that agents maintain as they work. Components use stable {#id} anchors, files: globs connect observed writes to components, needs: draws dependency arrows, and links: draws dashed connections. Task status uses [ ] (todo), [~] (working), [x] (done), and [!] (stuck). The by: field records which agent or contributor completed a task; from: separates agent intent from roadmap backlog. Agents record plan-affecting decisions in a ## decisions section before acting on them.

Local-First Architecture

The daemon binds to 127.0.0.1 only and never sends a prompt or edits code. There is no database, build step, cloud service, or account required. The entire runtime model comes from PLAN.md (the durable map) and local filesystem events (the live trail, which fades as activity ages). The project has been tested on a 78,000-file repository, using breadth-first tree reads with per-directory caps and SSE activity ticks to keep the interface responsive.

Current Status

The repository was created on 2026-08-21 and last pushed on 2026-08-25, with 267 stars and 14 forks as of late August 2026. The project is actively maintained and available on npm as agenttrail.