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.
- Open source
- MIT licensed
- Free to self-host
How does Agent Graph help?
Agent Graph integrates with leading AI coding providers like Claude Code, Codex and Cursor 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, or run this site yourself.
Open source, and free
All of Agent Graph is open source under the MIT licence: the agent-graph command, the viewer, and this site. Read it, fork it, change it, use it at work. github.com/shaneosullivan/agent-graph
MIT licensed
No open-core catch and no closed parts. Every line, this site included, is on GitHub to use as you like.
Free on your computer
Recording your agents and agent-graph view are free for ever, with no account, and nothing leaves your machine.
Free to self-host
Deploy this site to your own domain, on Vercel and Firebase’s free plans, and share live from anywhere without paying anything. Here’s how
You don’t have to host it yourself, though. Even easier, make an account here, and agent-graph watch-remote shares your agents live to it, with nothing to deploy. (What it costs.)
Install Agent Graph
For macOS, Linux and Windows, on ARM and x86_64. It records Claude Code, Codex and Cursor, on your computer and in their clouds.
- Install
agent-graph0.1.25:brew tap chofter/tap brew trust chofter/tap brew install --cask chofter/tap/agent-graphOr, without Homebrew:curl -fsSL https://agent-graph.net/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 codexUsing Cursor? Record its chats, in the app and its CLI:agent-graph install cursor
- Install
agent-graph0.1.25:curl -fsSL https://agent-graph.net/install.sh | shNo curl? With wget:wget -qO- https://agent-graph.net/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 codexUsing Cursor? Record its chats, in the app and its CLI:agent-graph install cursor
- Install
agent-graph0.1.25:irm https://agent-graph.net/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 codexUsing Cursor? Record its chats, in the app and its CLI:agent-graph install cursor
- Install
agent-graph0.1.25: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 codexUsing Cursor? Record its chats, in the app and its CLI:agent-graph install cursor
- 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:agent-graph.net 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://agent-graph.net/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):
agent-graph.netSet 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.
- On your computer, with agent-graph installed (as for macOS or Linux), go to the root folder of your copy of the GitHub repository Cursor’s cloud agents will work in, and add the cloud’s hooks to its
.cursor/hooks.json:agent-graph install cursor --cloud --scope project - Still in that repository, commit the file and push it to the branch cloud agents start from (usually
main). A cloud agent works in a clone from GitHub, so that’s where it finds the hooks. On your computer, and your teammates’, they do nothing.git add .cursor/hooks.json && git commit -m "Share Cursor cloud agents to Agent Graph" && git push - In this site’s account page, under API tokens, make a token, and copy it (it starts with
agt_). - At cursor.com/dashboard, open Cloud Agents, then Secrets, and add a secret named
AGENT_GRAPH_TOKEN, with the token as its value:AGENT_GRAPH_TOKEN - Still in Cursor, open the settings of the cloud environment for that repository, and set its Start Script to:
git pull --ff-onlyA cloud agent starts from the environment’s saved copy of the repository, which can be older than your latest push: without the hooks, if they were committed after the environment was made. This brings it up to date first. The hooks install agent-graph themselves, so the Install Script can stay as it is. - Start a cloud agent on that repository (at cursor.com/agents, or from the Cursor app). Its hooks install agent-graph on its machine, then record the agent and its subagents and share them live: watch them at /watch, where they’re labelled “Cursor cloud”, with the names Cursor gives them. Cursor runs no hooks for a new agent’s first message, so it’s recorded from the second.Nothing at /watch? Ask the agent to run
~/.local/bin/agent-graph diagnostics, which also says whether it started behind its branch, or see Troubleshooting.A cloud agent can read the token, as it can any secret, but it can only share to your account; delete it on your account page to stop it working.
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.