AI 编码智能体工作时改了什么、计划有没有推进，现在可以实时看清了。agenttrail 是一个本地开源的可观测层，把 Claude Code、Codex、Cursor 等编码智能体的计划、工具调用、文件改动与进度，实时映射成一张项目地图。项目 sodiumsun/agenttrail 目前约 631 个 star、43 个 fork，采用 MIT 协议，0.1.0 版本于 2026 年 8 月 24 日发布到 npm。
转录回放回答不了的问题
编码智能体连续运行半小时后，转录记录只能显示它调用了哪些工具，很难回答三个问题：它正在改哪个组件？计划推进到哪一步？有没有回头修改已经标记完成的部分？
agenttrail 用两类信号对照来回答：Declared（声明） 表示智能体声称自己在做的组件与任务；Observed（观察） 表示文件系统里它实际改动的文件。两者不一致的位置就是需要人工检查的地方。已完成的任务卡片一旦其文件再次被改动，会重新亮起。
看板上的内容
运行后浏览器打开一个本地看板（仅绑定 127.0.0.1），可以看到：
- 5–9 个真实组件组成的地图，带依赖箭头、进度与 done / working / blocked 状态
- 当前 Claude Code 运行的任务列表、流式工具调用、已用时长与最近调用
- 智能体正在工作的组件内的会话计划，运行结束几小时后淡出
- 类似 VS Code 的文件树，实时标出「刚刚被改动」的文件
PLAN.md：让智能体维护地图
地图的静态骨架来自仓库里的 PLAN.md。该文件用固定格式记录组件（稳定 id）、任务状态（[x] 完成、[~] 进行中、[!] 卡住）、依赖关系与负责人。智能体在工作中按约定更新这份文件，agenttrail 负责把它画出来。计划过时时，让智能体执行 re-verify PLAN.md against the code 即可重新校准。
一次初始化，之后零维护
在仓库执行 npx agenttrail init：创建初始 PLAN.md，把约定追加到 CLAUDE.md / AGENTS.md，把 .agenttrail/ 加入 .gitignore，并安装本地的 Claude Code hooks（安装前会征求同意）。日常使用只需 npx agenttrail 打开看板；npx agenttrail up 重启所有历史看板，npx agenttrail autostart 让看板随登录自启。
本地优先与零依赖
守护进程是一个约 470 行的零依赖 Node 文件，界面是单个静态 HTML 文件；没有数据库、没有构建步骤、没有云服务、没有账号、没有遥测。每个仓库一个守护进程，多个看板集中在同一个标签切换器中。作者在 78,000 个文件的仓库上做过实测，文件树按目录上限广度优先读取，过大时看板会提示视图被截断。
支持的智能体
| 智能体 | 实时活动 | 运行卡片 | 地图维护 |
|---|---|---|---|
| Claude Code | 文件监听 | 本地 hooks | CLAUDE.md |
| OpenAI Codex | 文件监听 | — | AGENTS.md |
| Cursor 及其他 | 文件监听 | — | AGENTS.md |
agenttrail 只观察、不干预：运行期间从不向智能体发送提示词，也不修改代码，看板本身是只读的。
结论
LLM 可观测性不应只停留在 trace、延迟、token 与成本这些指标上。agenttrail 提供的是另一个视角：工作在仓库里的形状——智能体在动哪个组件、跑什么工具、改哪些文件、计划有没有推进。如果你日常依赖编码智能体，花两分钟执行 npx agenttrail init，就能在浏览器里实时看到它的工作现场。