# agenttrail

> Local, open-source observability layer for AI coding agents that turns plans, tool calls, file changes, and progress into a live project map.

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`.

## Features
- Live project map of AI coding agent activity
- Reconciles declared plan vs. observed file changes
- Claude Code integration via local hooks and CLAUDE.md
- OpenAI Codex and Cursor support via file watcher
- PLAN.md convention for agent-maintained component maps
- VS Code-style repo tree with live file activity accents
- Run cards with task lists, streaming tool lines, and elapsed time
- Multi-repo tab switcher in a single dashboard
- No account, no telemetry, no cloud dependency
- Runs on localhost (127.0.0.1 only)
- Single npx command to start
- init command to bootstrap full setup
- Backfill prompt to let agents draw the component map
- Dependency arrows and dashed links between components
- Task status tracking: todo, working, done, blocked
- Agent attribution on completed tasks (Claude spark, OpenAI blossom, contributor initials)
- Tested on 78k-file repositories

## Integrations
Claude Code, OpenAI Codex, Cursor, npm, Node.js

## Platforms
WEB, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/sodiumsun/agenttrail
- Documentation: https://github.com/sodiumsun/agenttrail#readme
- Repository: https://github.com/sodiumsun/agenttrail
- EveryDev.ai: https://www.everydev.ai/tools/agenttrail