agenttrail: Real-time Observability for Your AI Coding Agents
This repository profile is provided by osrepos.com, an open source repository discovery platform.
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.
Repository Information
Topics
Click on any tag to explore related repositories
Use at your own risk
OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.
Introduction
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.
Why Use and Benefits
When 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:
- Live Project Map: Visualize 5-9 real components with dependencies, progress, and status (done, working, blocked).
- Real-time Activity: See current Claude Code runs, including task lists, streaming tool lines, elapsed time, and recent calls.
- File System Monitoring: A VS Code-style repo tree with "just touched" accents and a "Working" signal.
- 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.1only and never sends prompts or edits your code. - Agent-Maintained Map: Agents can maintain the
PLAN.mdfile, whichagenttrailuses to draw the component map, reducing manual project management overhead. - 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.
Installation
agenttrail is designed for quick and easy local setup. Navigate to your repository and run:
cd your-repo
npx agenttrail
The browser will open on the live board. For the full component map and to enable agents to maintain the plan, run this once:
npx agenttrail init
This command adds the agenttrail convention to CLAUDE.md and AGENTS.md, creates a starter PLAN.md, and installs additive local Claude Code hooks.
Examples
Once 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.
Links
- GitHub Repository: https://github.com/sodiumsun/agenttrail
- npm Package: https://www.npmjs.com/package/agenttrail
Source repository
Open the original repository on GitHub.