Agenttrail
Local project, task, and role observability for AI coding-agent workflows.
- Source repo
- sodiumsun/agenttrail
- Stars
- ★ 963
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 77/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer running local Codex or Claude Code sessions who wants one browser view of active tasks, session evidence, and changing project responsibilities.
- Not a fit if
- Teams needing stable production monitoring: Kitchen is an experimental public preview
- Users on Windows or native Cursor: both remain unverified
- Users wanting an in-editor VS Code Marketplace extension: none is shipped
- Source review
- 77/100 · Good
What does this agent do, and when should you use it?
Agenttrail is a local observability project with two independently runnable views: Map and Kitchen. Map combines intent declared in PLAN.md with file activity to display components, dependencies, progress, a live file tree, and session trails. Kitchen turns current tasks, inferred responsibilities, contributions, and reported completions into a browser-based 3D cooking scene. Both services bind to 127.0.0.1 and require no account, API key, model call, telemetry, transcript upload, or cloud service; neither launches agents, assigns work, approves actions, or decides that work is finished. It is a practical fit for developers who want an inspectable companion to local Codex, Claude Code, or supported Cursor workflows without sending agent activity to a hosted monitoring platform.
Kitchen starts with npx agenttrail-kitchen . and reads accessible local Codex or Claude Code session logs, supported native todos, file activity, and optional Claude/Cursor hook events. Its browser interface represents responsibilities as chefs, todos as tickets and dishes, observed work as cooking, and reported todo completion as delivery; users can select chefs or tickets to inspect supporting evidence. It automatically observes local activity, infers responsibilities, and detects available todo completion, while confirmed handoffs and one todo shared across separate sessions require explicit metadata. Map starts with npx agenttrail and joins PLAN.md component definitions, task states, files: patterns, needs: dependencies, and links: relationships with observed filesystem changes to produce a project map and session trails. Optional Claude Code hooks add session and tool activity plus legacy TodoWrite lists to Map; Codex, Cursor, and other tools contribute there primarily through file observation and the shared plan convention. Ordinary watching does not edit the repository, but npx agenttrail init creates plan and agent-convention files, offers optional hooks, and updates .gitignore.
- A developer running local Codex or Claude Code sessions who wants one browser view of active tasks, session evidence, and changing project responsibilities.
- A team maintaining a component-heavy repository that wants to compare a declared PLAN.md roadmap with actual file writes and dependency relationships.
- A developer recording or demonstrating agent work who wants Kitchen's 3D task visualization while retaining inspectable evidence behind each chef and ticket.
- An engineer using Codex or Claude Code from VS Code who wants a browser companion launched from the integrated terminal rather than an editor extension.
- A security-conscious team evaluating local-first monitoring that does not require telemetry, transcript uploads, accounts, or cloud model calls.
- A prospective user without a running agent who wants to evaluate the interface through the labeled
--exampleworkflow.
How do you install or deploy this agent?
Prerequisites are Node.js 20+, a WebGL-capable browser, and a local project directory. No account or API key is required for basic use. From the repository to observe, run:
npx agenttrail-kitchen .The Map view is installed and run independently with:
npx agenttrailTo pin the documented Kitchen preview release, run:
npx [email protected] .To build Kitchen from source:
git clone https://github.com/sodiumsun/agenttrail.git
cd agenttrail
npm ci --prefix packages/kitchen
npm run build --prefix packages/kitchen
npm start --prefix packages/kitchen -- --project /absolute/path/to/your/repoHow do you use this agent?
Run npx agenttrail-kitchen . inside the target repository and leave the terminal open. The browser opens on localhost:4780, or the next available port; continue working in a local Codex or Claude Code session while Kitchen discovers accessible logs and todos. Claude Code and Cursor can also use optional hooks configured through Connect agents. To explore without live agent activity, run npx agenttrail-kitchen . --example, advance with Next example step, and select Live to return to the real repository. For the component map, run npx agenttrail init, review the proposed writes, maintain the generated PLAN.md convention, and then launch npx agenttrail. Noninteractive init assumes consent, so it should only be run when repository configuration changes are intended.
What are this agent's strengths and limitations?
- Local-first operation: both services bind to 127.0.0.1 and need no account, API key, telemetry, transcript upload, model call, or cloud service.
- Two distinct views cover different decisions: Map focuses on components, dependencies, and files, while Kitchen focuses on tasks, role contributions, and reported completion.
- Kitchen automatically reads accessible local Codex and Claude Code logs; basic observation does not require PLAN.md, copied files, or a new agent session.
- The interface preserves important evidence boundaries: an ended turn is not treated as a shipped deliverable, and missing plans remain progress unknown.
- Normal observation neither launches nor controls coding agents and does not edit the watched repository.
- Kitchen is an experimental public preview, provider log formats may change, and post-restart history is reconstructed only from observations still available.
- Adoption requires Node.js 20+ and a WebGL browser; cloud or remote sessions without logs on the Kitchen host are not discovered automatically.
- Windows and native Cursor behavior remain unverified, although Cursor adapter tests pass.
- Map and Kitchen have separate local services and provider adapters, so their coverage and retained history are not identical.
- Cross-session shared todos and confirmed artifact handoffs require explicit metadata rather than being reliably inferred from ordinary activity.
- There is no Agenttrail VS Code Marketplace extension; users must keep the browser companion beside their editor.
How does this agent compare with similar options?
Map and Kitchen are alternative views within the same repository and can be used independently. Choose Map for component structure, dependencies, file activity, and PLAN.md-based progress; choose Kitchen for current todos, responsibility contributions, reported completion, and a 3D collaboration metaphor. Kitchen includes local Codex/Claude session adapters and optional Cursor hooks, while Map relies mainly on file observation and the plan convention for Codex, Cursor, and other tools. Their activity coverage and history are therefore not equivalent.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Agenttrail This agent | 77 · Good | CLIFree | ★ 963 | 1mo ago | JavaScript | Codex · Claude Code |
| Mission Control | 63 · Some gaps | Self-hosted serviceFree + model costs | ★ 6.4k | 1mo ago | TypeScript | — |
| AgentAcct | 61 · Some gaps | CLIFree | ★ 756 | 23d ago | Python | Codex · Claude Code |
| OpenClaw Monitor | 38 · Major gaps | Self-hosted serviceFree | ★ 13 | 5mo ago | JavaScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The materials explicitly state that services bind only to 127.0.0.1, require no account or cloud service, and do not modify the repository during ordinary watching. They also identify read sources, browser-bound fields, local storage, and potentially visible sensitive details, earning strong data-flow transparency. Read-only CI permissions and commit-pinned actions support least privilege and supply-chain hygiene. Deductions apply because Map init edits several files and assumes yes when noninteractive; optional hooks alter provider settings, while the supplied files do not show granular confirmations, complete rollback procedures, dependency auditing, or the allowlist implementation. Repository metadata, an MIT copyright holder, and contribution links provide attribution, but registry verification is absent and maintainer identity remains a repository claim.
The README, package metadata, license, and CI are internally consistent about positioning, Node.js 20+, licensing, and the two independent views. CI covers Node 20/22/24, Linux, macOS, build, checks, tests, and packaging. Installation uses npm ci, but no lockfile contents, offline strategy, or dependency-outage handling are supplied. The FAQ offers useful diagnosis for quiet views, missing logs, and remote sessions, although code-level error messages and comprehensive failure paths are not shown.
The documentation thoroughly distinguishes scenarios for Map, Kitchen, Codex, Claude Code, Cursor, VS Code, and unsupported tools. It clearly limits the product to observation rather than agent execution, approvals, coordination, or proof of deployment. Commands, explicit connection flows, optional hooks, and the PLAN.md convention provide reasonably precise activation, but native-event coverage varies by provider and local log formats may change. Requirements are stated clearly; macOS has reported use and Linux has automated checks, while Windows, native Cursor behavior, and remote sessions without host logs remain unsupported or unverified.
The README has strong navigation, comparison tables, installation commands, a PLAN.md example, FAQ, limitations, and contribution routes. The full MIT license agrees with package metadata. The Map/Kitchen relationship is explained, though separate package names and version lines—especially Kitchen's alpha release—add stability and comprehension cost. A release document is linked but no changelog contents, cadence, or compatibility policy are supplied, so versioning evidence is thin. A copyright holder plus issue and contribution links indicate responsibility, but no explicit maintenance team, support commitment, or update policy is shown.
Screenshots, interface mappings, example mode, and inspectable-evidence descriptions support useful outputs for understanding file activity, tasks, and role contributions. The tool plausibly reduces the need to reconcile several terminals and can be tried without an account, API key, or package build. Deductions apply because benefits are supported mainly by project-authored descriptions and recordings rather than comparative or user evidence; separate services, an experimental 3D interface, adapter differences, and dependence on available logs impose setup and interpretation costs.
Major claims are tied to concrete commands, configuration files, data sources, CI steps, or referenced repository documentation, and the supplied README, package metadata, license, and workflow corroborate one another. However, the linked detailed documentation, implementation, test sources, lockfiles, and test results are not included, limiting traceability and independent corroboration for privacy controls, field allowlisting, and adapter behavior. The text carefully distinguishes scripted examples, observed events, inferred roles, provider-reported completion, pending validation, and unimplemented features, earning full marks for fact/inference separation.
- Map's noninteractive init assumes consent and creates or edits PLAN.md, CLAUDE.md, AGENTS.md, and .gitignore. Run it only when repository configuration is intended, and preserve or review existing changes first.
- The product reads local agent logs, task titles, paths, and some tool details. Inspect these for sensitive project or command information before recording, sharing the browser view, or exposing ~/.agenttrail data.
- Kitchen is an experimental alpha. Windows and native Cursor live behavior remain unverified, and remote sessions without logs on the host are not automatically discovered.
- The supplied evidence omits implementation code, lockfiles, and test results, so this review cannot independently confirm loopback binding, field allowlisting, hook reversibility, or dependency-security claims.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Agenttrail Kitchen is now on npm. From the local repo you want to watch: ```sh npx agenttrail-kitchen . ``` Requires Node.js 20+ and a browser with WebGL. Graphics and fonts are included. Add --example to explore a labeled scripted example, or use npx [email protected] . to pin this experimental release. …View on GitHub ↗
FAQ
Does Agenttrail require a paid account or API credentials?
Will it control or coordinate my coding agents?
Why is Kitchen showing no activity?
Does running Agenttrail modify the repository?
npx agenttrail init creates the plan and agent conventions and adds .agenttrail/ to .gitignore.