Troubleshooting

Start with agent-graph diagnostics, wherever sessions aren’t recorded or shared: on your computer, or in a cloud agent’s machine (ask the agent to run ~/.local/bin/agent-graph diagnostics). It checks everything Agent Graph needs there, names what’s wrong, and links to the fix below. Nothing secret is printed.

A cloud that’s set up to share reports its own problems: they show at the top of /watch.

Cursor runs none of the hooks in a hooks file

Cursor reads hooks.json as JSON with comments: a // or /* anywhere in a hook's command (https://…, say) starts a "comment" that breaks the file, and Cursor then runs none of its hooks, without saying so. agent-graph 0.1.20's install cursor --cloud wrote such a command.

Fix: Install the hooks again with agent-graph 0.1.21 or later (agent-graph install cursor, or for the cloud, agent-graph install cursor --cloud --scope project, then commit .cursor/hooks.json). A hook of your own with // in its command needs it written another way: in sh, https:/''/example.com is still https://example.com.

A hooks or settings file isn't valid JSON

The agent can't read the file its hooks are in, so it runs none of them.

Fix: Open the file named in the report and fix the JSON (a missing comma or quote, usually). Installing again won't change a file it can't read.

An agent has no Agent Graph hooks

The agent is installed on this computer, but nothing records its sessions.

Fix: Run agent-graph install claude-code (or codex, or cursor), then start a new session: sessions already running aren't recorded.

In Claude Code cloud: On your computer, in the repository, run agent-graph install claude-code --cloud, commit .claude/settings.json and push it to the branch cloud sessions start from, then start a new session.
In Codex cloud: Edit the environment at chatgpt.com/codex: its setup script needs both lines from the site's Codex cloud steps. Click Reset cache, and start a new task.
In Cursor cloud: On your computer, in the repository, run agent-graph install cursor --cloud --scope project, commit .cursor/hooks.json and push it to the branch cloud agents start from, then start a new agent.

The committed cloud hooks are from an older agent-graph

A cloud's hooks are committed to the repository, so they stay as an older agent-graph wrote them until they're installed again: without what's been fixed or added since (newer hooks keep agent-graph itself up to date in the cloud, for one).

Fix: On your computer, with the latest agent-graph, install the cloud hooks again in the repository, and commit and push them.

In Claude Code cloud: On your computer, in the repository, with the latest agent-graph: run agent-graph install claude-code --cloud, then commit .claude/settings.json and push it.
In Cursor cloud: On your computer, in the repository, with the latest agent-graph: run agent-graph install cursor --cloud --scope project, then commit .cursor/hooks.json and push it.

A hook runs a program that isn't there

An Agent Graph hook names an agent-graph that's been moved or deleted (an upgrade by another route, or a build folder cleaned), so it does nothing.

Fix: Run agent-graph install <agent> again with the agent-graph you use now: it points the hooks at it.

Codex doesn't trust Agent Graph's hooks

Codex runs a hook only once it's trusted in its config.toml, and these aren't (or were changed since they were trusted).

Fix: Run agent-graph install codex again, which trusts them, then restart Codex (and the ChatGPT app, with Cmd+Q).

Nothing has been recorded

Agent Graph's hooks are in place, but no session has been recorded: the agent hasn't started a session since, or its hooks aren't running.

Fix: Start a new session in the agent (one already running isn't recorded). Still nothing? Run agent-graph diagnostics again: it names whatever stops the hooks.

In Claude Code cloud: The hooks come from the repository: check .claude/settings.json with the cloud hooks is committed on the branch the session started from (agent-graph install claude-code --cloud), and start a new session.
In Codex cloud: The environment's setup script installs the hooks: check it has both lines from the site's Codex cloud steps, click Reset cache on the environment's page, and start a new task.
In Cursor cloud: The hooks come from the repository: check .cursor/hooks.json with the cloud hooks is committed on the branch the agent started from (agent-graph install cursor --cloud --scope project), and start a new agent.

The cloud agent started from an older commit

A cloud agent works on a copy of the repository, which can start behind its branch (a cloud may restore an older copy, then catch up). The agent's hooks are read from the copy it starts with, so hooks committed since don't run, or run only later.

Fix: Check the agent starts on the branch with the hooks, and that the branch is pushed. Then start a new agent: one that starts on the latest commit runs the hooks from its first message.

In Cursor cloud: A Cursor cloud agent starts from its environment's saved copy of the repository, which can be older than your latest push. In Cursor, set the environment's Start Script to git pull --ff-only, so each agent brings it up to date first, then start a new agent.

Cursor cloud agents are named by their repository

A Cursor cloud agent's machine has no Cursor database to read its name from. Agent Graph asks the machine's own metadata (Cursor's Agent Metadata Socket) instead, which Cursor's own cloud machines have, once Cursor has named the agent. A machine without it (one of your own, say) names its agents by their repository.

Fix: Nothing to do on Cursor's cloud machines: the name comes once Cursor has given one. Elsewhere, Cursor's API can say it, with a Cursor API key: make one in Cursor's dashboard and add it as a secret named CURSOR_API_KEY. The agent can read it, as it can any secret, and it can do whatever your Cursor API key can: leave it out if you'd rather.

Agent Graph can't write its data folder

Sessions are recorded in ~/.agent-graph (or $AGENT_GRAPH_HOME), and that folder can't be made or written to.

Fix: Check the folder's owner and permissions (ls -ld ~/.agent-graph), or set AGENT_GRAPH_HOME to a folder you can write to.

The site can't be reached

Sharing sends what's recorded to the site, and nothing answers there: no network, a firewall, or a proxy in the way.

Fix: Check this computer can open the site in a browser. Behind a proxy, HTTPS_PROXY must be set for agent-graph too.

In Claude Code cloud: In the environment's settings at claude.ai/code, set network access to Custom, allowing agentgraph.chofter.com and firebasestorage.googleapis.com.
In Codex cloud: In the environment's settings at chatgpt.com/codex, turn on Agent internet access, add agentgraph.chofter.com to the additional allowed domains, and allow all HTTP methods.
In Cursor cloud: A cloud agent's machine can usually reach the internet: check your team's network settings in Cursor's dashboard allow agentgraph.chofter.com.

Something else answered for the site

A request to the site got an answer, but not the site's: a proxy's page, or a network that blocks it.

Fix: Allow the site through the proxy or firewall, for every HTTP method (sharing sends with POST).

In Codex cloud: In the environment's settings at chatgpt.com/codex, set Allowed HTTP Methods to All methods.

AGENT_GRAPH_TOKEN isn't set

In a cloud, sharing logs in with an API token from your account page, given as AGENT_GRAPH_TOKEN, and there's none.

Fix: Make a token on the site's account page, under API tokens, and set AGENT_GRAPH_TOKEN to it.

In Claude Code cloud: At claude.ai/code, open the environment's settings and add AGENT_GRAPH_TOKEN=agt_… under environment variables, then start a new session.
In Codex cloud: At chatgpt.com/codex, edit the environment and add AGENT_GRAPH_TOKEN under Environment variables (not Secrets, which only the setup script gets), then start a new task.
In Cursor cloud: At cursor.com/dashboard, open Cloud Agents, then Secrets, and add AGENT_GRAPH_TOKEN, then start a new agent.

The login isn't one the site knows

The token (AGENT_GRAPH_TOKEN, or this computer's saved login) has been revoked or deleted on the account page, or was mistyped.

Fix: Make a new token on the account page, under API tokens, and use it in place of the old one. On your own computer, agent-graph watch-remote logs in again.

In Claude Code cloud: Replace AGENT_GRAPH_TOKEN in the environment's settings at claude.ai/code with a new token, then start a new session.
In Codex cloud: Replace AGENT_GRAPH_TOKEN in the environment's variables at chatgpt.com/codex with a new token, click Reset cache, and start a new task.
In Cursor cloud: Replace the AGENT_GRAPH_TOKEN secret in Cursor's dashboard (Cloud Agents → Secrets) with a new token, then start a new agent.

In Claude Code cloud: The cloud installs the latest release itself, in each new session.
In Codex cloud: Click Reset cache on the environment's page, so its setup script installs the latest release.
In Cursor cloud: The cloud installs the latest release itself, on each new agent's machine.