agtrace CLI
A terminal dashboard for Claude Code and Codex: a tree of agents with live status, a tool-call feed and context headroom.
- 64 ★ on the repository
- Last commit
- Apache-2.0
Minimal access
Why this level
- Reads local session logs, which may hold paths, commands and output containing secrets.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/agtraceDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Reads local session logs, which may hold paths, commands and output containing secrets.
This is third-party code. Review the repository files before installing.
What it does
agtrace reads Claude Code and Codex logs and shows them in the `agtrace watch` interface. The lead agent, its teammates, background subagents and Codex child threads form one live tree with each one's status and context window fill. A feed shows tool calls, subagent spawns, compactions and model changes, and a shared channel shows who asked whom for what and what came back. The `agtrace session list` and `agtrace session show` commands inspect past sessions, and `agtrace lab grep` searches all logs. Through the `agtrace mcp serve` MCP server an agent queries its own history: what it did yesterday and which errors occurred.
Who it is for. Developers who run Claude Code or Codex with several subagents and want to see what each is doing and when to start a new session.
Good fit when
- There has been no output for minutes and it is unclear whether it is looping or waiting on a subagent.
- Context fills fast and you need a headroom gauge to decide when to compact or start over.
- One task runs teammates and child threads and you want a shared view of their messages.
- You must find an error seen in past sessions across all logs at once.
- Yesterday's decisions should be pulled from the logs by an MCP query, with no retelling by hand.
Not a fit when
- The agent is neither Claude Code nor Codex: agtrace parses no other logs.
- Versions older than Claude Code 2.1.24x and Codex 0.153: there are no parsers for old formats.
- You need a token cost estimate at price lists: the project is about watching sessions.
Example request
Search past sessions for timeout errors and tell me how we fixed them back then.Limitations
Supported are Claude Code 2.1.24x or newer, meaning logs from September 2026, and Codex 0.153 or newer. Old formats are not parsed, and undecodable lines are counted as diagnostics and skipped. First-time setup runs `agtrace init`. The package installs through npm or cargo, so Node.js or Rust is needed. The dashboard only reads logs and changes nothing in the agents, but the MCP server gives an agent the whole archive of its past sessions, including whatever was printed in them.
How to disable. Remove the MCP connection with `claude mcp remove agtrace` or `codex mcp remove agtrace`, then the package through `npm uninstall -g @lanegrid/agtrace`.
FAQ
How do I install agtrace and start the dashboard?
Run `npm install -g @lanegrid/agtrace`, then `agtrace init` once. After that `agtrace watch` in a separate terminal opens the dashboard, and `agtrace demo` shows it on a synthetic multi-agent workspace.
How do I connect agtrace to Claude Code as MCP?
Run `claude mcp add agtrace -- agtrace mcp serve` and verify with `claude mcp list`. For Codex it is the same: `codex mcp add agtrace -- agtrace mcp serve`.
Which agent versions are supported?
Claude Code 2.1.24x or newer and Codex 0.153 or newer. Old log formats are not parsed, and lines that cannot be read are skipped and counted in diagnostics.
What if Claude Desktop cannot find node?
With version managers such as mise, nvm, asdf and volta, put the full path to `node` shown by `which node` into the configuration. Details are in the MCP integration guide.
Can I embed agtrace in my own tool?
Yes, tool builders have the Rust `agtrace-sdk` library. Add it as a dependency in `Cargo.toml`, and examples live in `crates/agtrace-sdk/examples`.
Discussion
No questions or reviews yet.
Related
CLI toolsAn htop-like terminal panel for AI agents: Claude Code, Codex, OpenCode and Devin sessions, CPU, tokens and cost.
Claude Watch draws a localhost map of project logic, shows Claude Code tool calls live and answers questions
A transparent wrapper for Claude Code and Codex: a local gateway records run events and trajectories without changing the agent.
OpenTelemetry-based CLI tracing for Claude Code, Cursor and Codex sessions, showing what the agent actually did and what it cost
Native macOS terminal with an MCP server and CLI: agents see panes, commands and output, and you grant permissions in one window
A local dashboard for Claude Code and Codex sessions: who is working, who waits for you, plus a 3D aquarium and Stream Deck
README in short
The author describes working with agents as a black box and wrote the dashboard he now always keeps alongside. Installation and the main commands take a few lines, the rest sits in the documentation.