Set up a coding agent to work with Agent Graph. For Claude Code this does two things:

1. Adds hooks to Claude Code's settings, so every new session is recorded, including sessions one starts from its shell (claude -p, codex exec, agent-graph run), which appear under it. Each hook runs agent-graph emit in the background: it takes a few milliseconds, never blocks the agent, and never sends anything anywhere. Everything else in the settings file is kept, and the file as it was without Agent Graph is backed up beside it (settings.json.agent-graph.bak); installing again or uninstalling keeps that backup. Sessions that were already running aren't recorded; start a new one. Installing again brings older hooks up to date.
2. Adds an /agent-graph command (a skill). Run it in any session for a picture of the session and a short summary of what needs you, what looks stuck and what's in progress. /agent-graph all covers every session from the last day, and /agent-graph share gives you a live link. Claude can also use it by itself when you ask how your agents are doing.

For Codex it does the same: hooks in Codex's hooks file (~/.codex/hooks.json, or $CODEX_HOME's), with the file as it was backed up beside it (hooks.json.agent-graph.bak), and the $agent-graph command. Codex only runs a hook once it's trusted, so it also trusts Agent Graph's, in Codex's config.toml, as Codex's /hooks would (backing that file up too, as config.toml.agent-graph.bak), and turns on Codex's plan tool (update_plan, off by default) unless that file already says either way. Nothing else there changes. Codex reads its hooks only when it starts, so afterwards restart the ChatGPT app (quit it with Cmd+Q) and any Codex already running in a terminal; the install ends by saying so. Sessions in the terminal and in the ChatGPT desktop app (which runs the same Codex) are recorded: a session's plan, the subagents it starts and waits for, when it needs your approval or an answer, and sessions it starts from its shell.

In the cloud: install claude-code --cloud adds hooks for Claude Code's cloud (claude.ai/code) to a project's settings, to commit; install codex --cloud, run in a Codex cloud environment's setup script (chatgpt.com/codex), adds hooks for Codex's cloud to Codex's own files there (in /opt/codex, its home in the cloud). Either way, each cloud session is recorded and shared live, at agentgraph.chofter.com/watch, to the account whose API token the environment gives as AGENT_GRAPH_TOKEN. The site's Download section has the steps, for each.

For Gemini CLI it adds just the command for now. Its own sessions aren't recorded yet, so it shows the Claude Code and Codex sessions that are.

Where the command goes (with --scope user)

What --scope changes

It lists what it will change and asks before writing: --yes skips the question, and --dry-run only shows the changes. Installing again changes nothing unless something is out of date. A command file of the same name that you wrote yourself is never overwritten.

Remove what install added: Agent Graph's hooks from the agent's settings, and the /agent-graph command if Agent Graph wrote it.

Everything else in the settings file is kept, and so is the backup install made of it before it had the hooks (settings.json.agent-graph.bak). A settings file left with nothing in it ({}) is removed too, unless there's a backup beside it, and so is a .claude, .agents or .gemini folder left empty. A command file you wrote yourself is left alone. Use the same --scope you installed with.

What's already been recorded stays in ~/.agent-graph; delete that folder to remove it.

Watch the graph live in this terminal.

Takes over the terminal like top and redraws as events arrive. The top line sums everything up: how many sessions and working agents, and, in colour, how many need you, look stuck or are deadlocked. Below it, each session is a tree of its agents, most recently active first:

claude-code:e0000002  search-indexer  [working]  Rebuilding the index schema
└─ Explore a91d0160  [working] (stale?)  Profile the slow bulk import

How to read it

Keys

It checks for new events four times a second, and redraws at least every five seconds so "stale?" keeps up with the clock. Lines are cut to the terminal's width; if there are more than fit, it says how many more.

When its output isn't a terminal (piped or redirected), it prints the whole picture each time something changes instead, so it can be logged.

Watch the graph live in your browser, and step back through its history.

Serves a web page on port 7777 (or --port) until you stop it with Ctrl+C, and prints its link (http://127.0.0.1:7777/?key=…), which carries a key made for this run: only someone with the link can use it, so other accounts on the machine agent-graph runs on can't. It's only reachable from that machine, and it refuses requests made by other websites. --open opens the link in your browser. If a viewer is already running on the port (one from an older version, say), it's stopped and this one takes its place; anything else on the port is left alone.

The page has

The page updates as events arrive, without reloading.

Print the graph once, as text, and exit.

Shows each session active in the last day (--all for every one) with its agents underneath, using the same markers as tail (agent-graph tail -h explains them). Handy in scripts, or to paste into a message.

Save a picture of a session and print where it went.

The picture is sized for a phone (1080 pixels wide). From the top: the session's name and state, a callout for anything that needs you, its agents as a tree (stuck ones flagged), and its task list. A big session shows its first 30 agents and counts the rest. It's made for sharing: an agent can run this and send you the image, which is what the /agent-graph command does.

Which session it draws

Only the file's path is printed, so scripts can use it. By default the picture goes in ~/.agent-graph/images/ with a new name each time. --out chooses the file, and its extension chooses the format: .png, .svg, or .json. As .json, it's the graph as data: with --session or --all, just the sessions they choose and any they exchanged messages with, plus any of those wait on (directly or not); with neither, every session, as --json prints. It won't replace a file that's already there unless you add --force.

Share the graph live on the web, to your account, and print where to see it.

It sends the event log to the Agent Graph site (https://agentgraph.chofter.com, or --url), prints the address of your live share straight away (the site's /watch), then sends each new event as it's recorded, until you stop it with Ctrl+C. Open it anywhere you're logged in, including on a phone: it's the same viewer as agent-graph view, timeline and all.

What's shared: every session on the machine agent-graph runs on, or just one with --session (--session current for the one this runs in). Agent Graph records task names and agent descriptions, not prompts or tool output (unless you've set AGENT_GRAPH_CAPTURE_BODIES=1). The site stores it encrypted.

Logging in

The first time, it opens your browser at the site's login page: log in with Google, or an email and password (or create an account), and agent-graph is told when you're done. Its login is kept in ~/.agent-graph/account.json, readable only by you, for next time. --logout ends it (on the site too), and you can log a computer out from the site's account page. If it can't open a browser, it prints the address to open yourself.

On a machine where you can't log in in a browser (a cloud instance, say), make an API token on your account page instead, and give it as AGENT_GRAPH_TOKEN: AGENT_GRAPH_TOKEN=agt_… agent-graph watch-remote. The site's asked whose it is, and it's kept as that machine's login, so --autostart works with it too. Revoke it on your account page when you're done with it.

Subscribing

Where the site charges for sharing live, a new account can share for its first week (or however long the site allows) without paying. After that, it opens your account page in the browser for you to subscribe, and waits: once you have, it carries on sharing by itself. A run that's sharing when the time runs out does the same.

Who can see it

Only you, logged in to the site: /watch shows your latest live share. Nobody else can open it. Your login is only sent over HTTPS, or to your own machine.

Who can change it

Only you. The site gives the share a key when it's made, and every update must carry it. It's kept in ~/.agent-graph/shares/, readable only by you, so the next run can carry on.

It checks for new events once a second, and sends them at most every 5 seconds, together. If the connection drops, new events are kept and sent when it's back. If the site refuses them outright, it stops and says why. The site deletes a share that has had no new events for a week: sharing it then stops.

Running it again

The next run for the same site, account and sessions carries on with the same share. What the site already has isn't sent again: it starts again from one summary of the log as it is now, and deletes what came before. --new starts a new share instead, as does logging in as someone else, and a share the site has deleted. If it's being shared now, by another run, it's left to that run.

Sharing whenever you log in

--autostart has it start by itself whenever you log in to this computer, and share every session, so you never have to run it. On macOS it's a launchd agent (~/Library/LaunchAgents/com.chofter.agent-graph.watch-remote.plist; what it says goes to watch-remote.log in ~/.agent-graph); on Linux, a systemd user service (agent-graph-watch-remote.service; journalctl --user -u agent-graph-watch-remote shows what it says); on Windows, one of your Startup apps (AgentGraphWatchRemote, in the registry's Run key; what it says goes to watch-remote.log in %USERPROFILE%\.agent-graph), which starts it without a window. If it fails (the network isn't up yet, say), it's started again a minute later. It never opens a browser: if you have to log in again, it stops and says so, until you do. Setting it up logs you in first, if you aren't. agent-graph install claude-code offers to set it up too. --no-autostart stops it and removes it.

Runs a command and puts it in the graph as a node of its own: working while it runs, then completed, or failed with its exit code. Its input and output pass straight through, and run exits with its exit code.

Use it for agents without hooks (agent-graph run -- aider), or for a script that starts several agents, which then appear under it.

How it links

• Started from an agent's shell (or anywhere AGENT_GRAPH_PARENT is set), it goes under that session.
• The command gets AGENT_GRAPH_PARENT and TRACEPARENT for the new node, so agents it starts that have Agent Graph's hooks go under it.
• When a Claude Code or Codex session runs it in its shell, the session waits on it, as on any agent it starts.

Put the command after --, so its own options aren't read as run's.