Agent GraphLead your army of agents with confidence
We humans are still an integral cog in the AI machine, but when we're running dozens (or even just 4 or 5) agents or sessions, we often become the bottleneck. An agent is waiting on our input, a session is blocked by a child session it spawned, and unless we monitor them like a hawk, they remain blocked.
Agent Graph solves this.
How does Agent Graph help?
Agent Graph integrates with leading AI coding providers like Claude Code and Codex to record a log of all your sessions, agents and tasks and the dependencies between them. It highlights where you are needed at any time, what work is ongoing, and what is completed. You can run it completely locally, it starts a local web server that you use on your computer.
What about when I'm away from my computer?
To keep up with your agents on the move, you simply run agent-graph watch-remote, and that streams your logs to this site, where you can track all your agent's work in a fully secure and private manner. This is completely optional, and you can of course keep all of your logs local on your machine. This entire project is open source too of course, so you can even fork it, deploy this site yourself to your own domain, and use it for your work instead of this site.
Install Agent Graph
For macOS, Linux and Windows, on ARM and x86_64. It records Claude Code and Codex, on your computer and in their clouds.
- Install
agent-graph0.1.19:brew tap chofter/tap brew trust chofter/tap brew install --cask chofter/tap/agent-graphOr, without Homebrew:curl -fsSL https://agentgraph.chofter.com/install.sh | shOr download the program itself (unpack it, and putagent-graphon your PATH):macOS · Apple siliconmacOS · Intel - Start recording Claude Code sessions:
agent-graph install claude-codeUsing Codex? Record its sessions too:agent-graph install codex
- Install
agent-graph0.1.19:curl -fsSL https://agentgraph.chofter.com/install.sh | shOr with Homebrew:brew tap chofter/tap brew trust chofter/tap brew install --cask chofter/tap/agent-graphOr download the program itself (unpack it, and putagent-graphon your PATH):Linux · x86_64Linux · ARM64 - Start recording Claude Code sessions:
agent-graph install claude-codeUsing Codex? Record its sessions too:agent-graph install codex
- Install
agent-graph0.1.19:irm https://agentgraph.chofter.com/install.ps1 | iexIn PowerShell. It puts agent-graph.exe in %USERPROFILE%\.local\bin, and adds that to your PATH. Run it again to upgrade.Or with Node (npm):npm install -g @chofter/agent-graphOr download the program itself (unpack it, and putagent-graphon your PATH):Windows · x64Windows · ARM64 - Start recording Claude Code sessions:
agent-graph install claude-codeUsing Codex? Record its sessions too:agent-graph install codex
- Install
agent-graph0.1.19:npm install -g @chofter/agent-graphFor macOS, Linux and Windows, with Node 16 or later. Install it globally, not with npx: the hooks run the program from where npm puts it. npm update -g @chofter/agent-graph upgrades it. - Start recording Claude Code sessions:
agent-graph install claude-codeUsing Codex? Record its sessions too:agent-graph install codex
- On your computer, with agent-graph installed (as for macOS or Linux), go to the root folder of your copy of the GitHub repository you’ll open in the cloud, and add the cloud’s hooks to its
.claude/settings.json:agent-graph install claude-code --cloud - Still in that repository, commit the file and push it to the branch cloud sessions start from (usually
main). A cloud session works in a fresh clone from GitHub, so that’s where it finds the hooks. On your computer they do nothing.git add .claude/settings.json && git commit -m "Share cloud sessions to Agent Graph" && git push - In this site’s account page, under API tokens, make a token, and copy it.
- At claude.ai/code, open the environment menu beside the repository picker, and open the settings of the environment you’ll use. (Not claude.ai’s own Settings page: its network settings are for chats, not Claude Code.) There, add the token under environment variables:
AGENT_GRAPH_TOKEN=agt_…and set network access to Custom, allowing these two domains:agentgraph.chofter.com firebasestorage.googleapis.comThe environment’s setup script can stay empty. - At claude.ai/code, start a session in that repository, with that environment. It installs agent-graph, records the session, and shares it live: watch it at /watch.
- On this site’s account page, under API tokens, make a token, and copy it (it starts with
agt_). It’s shown only once, so keep the page open until step 4. - Go to chatgpt.com/codex and sign in with your ChatGPT account. If you see a page that says “Build anything with Codex”, click Go to Cloud at its top right.
- Click the gear icon at the top right (beside the bell and your picture), then Environments. Click the environment for the GitHub repository you’ll work in (create one for it there first, if there isn’t one), then click Edit. Everything in steps 4 to 7 is on that Edit page. (Not ChatGPT’s own settings, whose options are for chats.)Each environment has its own settings: only tasks in an environment set up this way are recorded. If you have more than one, do steps 3 to 7 for each of them (step 9 says so again).
- Under Environment variables, add one named
AGENT_GRAPH_TOKEN, with the token from step 1 as its value:AGENT_GRAPH_TOKENNot under Secrets: a secret reaches only the setup script, not the task, so nothing would be shared. - Under Setup script, choose Manual, and add these two lines to the box, after anything already there:
curl -fsSL "https://agentgraph.chofter.com/install.sh?cache_bust=$(date +%s)" | sh ~/.local/bin/agent-graph install codex --cloud --yesThey install agent-graph in the cloud’s machine (not on your computer), and the hooks that record each task there and share it. - Under Agent internet access, choose On. Keep the Domain allowlist as it is, and in Additional allowed domains add (after a comma, if there are domains there already):
agentgraph.chofter.comSet Allowed HTTP Methods to All methods: sharing sends the session with POST requests. - Click Save environment, at the bottom right.
- Back on the environment’s page, click Use this, and give Codex a task. Its session is recorded and shared live: watch it at /watch, where it’s labelled “Codex cloud”. Every task in that environment is shared the same way, with nothing more to do.Nothing at /watch? On the environment’s page, click Reset cache, so the setup script runs again, then start a new task. Codex can read the token, as it can any environment variable, but it can only share to your account; delete it on your account page to stop it working.
- Using other environments too, ones you already had or new ones? Each needs the same settings: go back to Environments, and do steps 3 to 7 for each of them. You can use the same token in all of them. Tasks in an environment without them aren’t recorded.
See it in action
Example sessions, each showing something the viewer does. Each opens in a new tab: step through it with the timeline, and try the graph view.
- Waiting for youA session stopped at a permission prompt, beside one that's working: it's flagged, counted at the top of the list, and pulses until you answer.
- Tasks, done and to doOne session 12 tasks into 30, another checking them off as it goes: counts on every card, and the whole list in its details.
- Agents in parallelThree agents started at once: one finished, one failed, one still running, and the session waiting only on that one.
- Agents within agentsA plan that started an explorer, which started a worker: each three levels down, under the agent that asked for it.
- A deadlockTwo sessions each waiting on the other: both marked, with the wait drawn between them.
- Sessions a script startedA command run with agent-graph run that started two headless Claude Code sessions, both under it; and a session another one started from its shell.
- A large graphA migration run by six planners, each with explorers and workers under them: 61 sessions and agents, 40 tasks, some done, some running, one failed, one waiting for you.
- A busy teamA dozen sessions open at once, of every size: the large migration, busy ones, small ones, a Codex session, two waiting for you. Zoom out in the graph to see them all round the one you're on.
- Claude invoking CodexA real Claude Code session, building Agent Graph's Codex support, that started ten Codex sessions from its shell to test it: each under it, with their own subagents, plans, approvals and questions, and the times each waited for you.
- A busy dayEvery example at once, about thirty-five sessions: the list by folder, deadlocks and scripts, and everything the busy team was doing.
Share your logs
Paste or upload an Agent Graph log to get a link, get it from .agent-graph/events in your home folder. It opens a viewer you can step through: which session started which agents, who’s waiting on whom, what looks stuck, and what needs you. You can share the url with a teammate and it'll stay live for a week.
Share live from your machine
With the agent-graph command installed, this shares to your account (logging you in the first time) and keeps it up to date as your agents work. Only you can see it, at /watch:
agent-graph watch-remoteMore about sharing, and every other command, in the docs.
What the viewer shows
Needs you
Permission prompts, questions and plans waiting for your approval.
Stuck or deadlocked
Agents that went quiet while working, and sessions waiting on each other.
A timeline
Step through every event and see the graph exactly as it was at that moment.
Where logs live
Agent Graph records one file per session in ~/.agent-graph/events/ (on Windows, %USERPROFILE%\.agent-graph\events\). Upload any of them, or paste their contents.