{"name":"agenttrail: Real-time Observability for Your AI Coding Agents","description":"agenttrail provides a local, open-source observability layer for AI coding agents. It transforms agent plans, tool calls, and file changes from tools like Claude Code, OpenAI Codex, and Cursor into a live, zoomable project map. This allows developers to monitor agent progress and activity in real time, ensuring they know what their agents are doing as it happens.","github":"https://github.com/sodiumsun/agenttrail","url":"https://osrepos.com/repo/sodiumsun-agenttrail","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/sodiumsun-agenttrail","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/sodiumsun-agenttrail.md","json":"https://osrepos.com/repo/sodiumsun-agenttrail.json","topics":["agent-monitoring","ai-agents","coding-agents","developer-tools","observability","local-first","HTML","nodejs"],"keywords":["agent-monitoring","ai-agents","coding-agents","developer-tools","observability","local-first","HTML","nodejs"],"stars":null,"summary":"agenttrail provides a local, open-source observability layer for AI coding agents. It transforms agent plans, tool calls, and file changes from tools like Claude Code, OpenAI Codex, and Cursor into a live, zoomable project map. This allows developers to monitor agent progress and activity in real time, ensuring they know what their agents are doing as it happens.","content":"## Introduction\n\n`agenttrail` is an innovative, local-first observability tool designed for AI coding agents. It offers an infinite canvas where every repository becomes a region on a live, zoomable map, allowing you to monitor your AI agents' sessions, plans, tool calls, and file changes in real time. Built with zero dependencies, `agenttrail` supports agents like Claude Code, OpenAI Codex, and Cursor, providing crucial insights into their development process.\n\n## Why Use and Benefits\n\nWhen your AI coding agent is working, it is essential to know if it is making progress, if it is stuck, or if it is revisiting completed tasks. `agenttrail` addresses this by providing a clear, real-time visualization of agent activity. It shows both the agent's declared plan and the files it is actually modifying, highlighting any discrepancies. Key benefits include:\n\n*   **Live Project Map:** Visualize 5-9 real components with dependencies, progress, and status (done, working, blocked).\n*   **Real-time Activity:** See current Claude Code runs, including task lists, streaming tool lines, elapsed time, and recent calls.\n*   **File System Monitoring:** A VS Code-style repo tree with \"just touched\" accents and a \"Working\" signal.\n*   **Local-First & Private:** The daemon is a single, dependency-free Node file, and the interface is a static HTML file. There is no database, build step, cloud service, account, or telemetry. It binds to `127.0.0.1` only and never sends prompts or edits your code.\n*   **Agent-Maintained Map:** Agents can maintain the `PLAN.md` file, which `agenttrail` uses to draw the component map, reducing manual project management overhead.\n*   **Broad Agent Support:** Offers rich live views for Claude Code via local hooks, and file watcher support for OpenAI Codex, Cursor, and other file-editing agents.\n\n## Installation\n\n`agenttrail` is designed for quick and easy local setup. Navigate to your repository and run:\n\nbash\ncd your-repo\nnpx agenttrail\n\n\nThe browser will open on the live board. For the full component map and to enable agents to maintain the plan, run this once:\n\nbash\nnpx agenttrail init\n\n\nThis command adds the `agenttrail` convention to `CLAUDE.md` and `AGENTS.md`, creates a starter `PLAN.md`, and installs additive local Claude Code hooks.\n\n## Examples\n\nOnce `agenttrail` is running, you will see a dynamic dashboard reflecting your agent's work. For instance, a Claude session will appear with its plan, edits will stream live, and tasks will update their status in real time. The map moves as the work progresses, showing which components are being touched and their current state. If you have run `npx agenttrail init`, your agents can then be prompted to populate and maintain the `PLAN.md` file, providing a structured, verifiable project overview.\n\n## Links\n\n*   GitHub Repository: <a href=\"https://github.com/sodiumsun/agenttrail\" target=\"_blank\">https://github.com/sodiumsun/agenttrail</a>\n*   npm Package: <a href=\"https://www.npmjs.com/package/agenttrail\" target=\"_blank\">https://www.npmjs.com/package/agenttrail</a>","metrics":{"detailViews":0,"githubClicks":0},"dates":{"published":null,"modified":"2026-09-03T00:31:59.000Z"}}