All pages
Agents
Cursor
Connect Cursor to Golem through its hooks and MCP settings, and how a held call behaves in each of Cursor's run modes.
Cursor is connected when you install Golem, or when the Golem agent finds Cursor installed later. Golem registers one hook script for every Cursor lifecycle event, so it sees prompts, replies, tool calls, shell commands, MCP calls and file reads, and can stop the ones your rules forbid. The Cursor app and the Cursor CLI (cursor-agent) read the same files, so both are covered.
What Golem adds#
| File | What Golem adds |
|---|---|
~/.cursor/hooks.json | Golem's hook on each of Cursor's 21 lifecycle events, all running the same script |
~/.golem/hooks/cursor-hook.sh | That script. Golem writes it and rewrites it on every setup run, so it always matches the agent. |
~/.cursor/mcp.json | Two MCP servers, golem-witness and golem-context, which give Cursor's agent Golem's own tools |
~/.cursor/skills | The golem-fleet and safely skills, and sandbox and golem-sandbox on a Mac with the sandbox |
Golem's entries sit beside any hooks and MCP servers you already have, and golem setup-client changes only Golem's own. The hooks that can stop a call get a 45-second timeout; the rest record and return at once.
The hook script needs bash and python3 on the machine.
What a block looks like#
Golem can stop a call on six hooks: preToolUse, beforeShellExecution, beforeMCPExecution, beforeReadFile, beforeTabFileRead and subagentStart. That covers tool calls, shell commands, MCP calls, file reads, Tab's file reads and subagents. A refused call does not run, and Cursor shows Golem's reason to you and to its agent:
blocked by Golem policy (rule "no-force-push-to-main", decision gd_3f9a1c07b2e4d815). Trying again won't change this; if you need it, ask your security team and quote the decision id.Quote the decision id to your security team, or ask them for an exception from the terminal with golem exception <decision-id> --reason "why". See Block, hold and contain.
How a hold behaves in each run mode#
A rule set to Ask holds the call until someone decides. When the person at the keyboard decides, it depends on Cursor's run mode, because Cursor only puts a hook's question to you in Allowlist mode. In Auto-review and Run Everything it runs the call past the question. So the hook reads the run mode, from the app's own settings or the CLI's flags and ~/.cursor/cli-config.json, before it answers:
| Run mode | Shell command or MCP call | Any other tool |
|---|---|---|
| Allowlist | Cursor asks you, with Golem's reason | refused |
| Auto-review | refused | refused |
| Run Everything | refused | refused |
| Can't be read | refused | refused |
A hold is never turned into an allow. Each held call records the run mode it was decided under.
When the rule hands the decision to Golem's reviewer agent, the run mode does not matter: the hook holds the call for up to 35 seconds while the reviewer decides, then lets it through or refuses it. When the rule leaves it to your team in the console, the call is refused with a message saying so, because a hook cannot wait that long.
Type /safely in a Cursor chat to lock the session to read-only tools before the agent reads something you don't trust. See Safely.
What is captured#
| What | From |
|---|---|
| Your prompt, and the agent's reply and thinking | beforeSubmitPrompt, afterAgentResponse, afterAgentThought |
| Every tool call, its result or its failure | preToolUse, postToolUse, postToolUseFailure |
| Shell commands, with their output up to 64 KB | beforeShellExecution, afterShellExecution |
| MCP calls, to Golem's servers and your own | beforeMCPExecution, afterMCPExecution |
| Files read and edited, by the agent and by Tab | beforeReadFile, afterFileEdit, beforeTabFileRead, afterTabFileEdit |
| Subagents, sessions, compaction and opened workspaces | subagentStart, subagentStop, sessionStart, sessionEnd, preCompact, stop, workspaceOpen |
Each event also carries the model, Cursor's version, the workspace folders and whether the app or the CLI ran it. Sessions are recorded as agent cursor. The full content goes to your storage; the record holds its hash and signature. See What Golem captures.
The Cursor CLI in non-interactive mode (-p) fires the tool and shell hooks but not the prompt and reply hooks, so a -p run's tool calls are recorded and its prompt and reply are not.
Check it is working#
- Quit Cursor completely and reopen it. Closing the window is not enough: Cursor reads hooks and MCP servers at startup.
- In Cursor's MCP settings,
golem-witnessandgolem-contextshould show as connected. - Run
golem doctor. hook commands should say the registered commands resolve, and after the agent has run a tool, inline enforcement (cursor) should say its tool calls reach the hooks. - Send a short prompt and ask the agent to run
git status. The session appears in the console under Conversations, with the prompt, the command and the reply.
Limits#
- The hook fails open. If the Golem agent is not running or the script hits an error, the hook answers allow and Cursor carries on. Nothing is checked or recorded until the agent is back.
- Asking you needs Allowlist mode, and works only for shell commands and MCP calls. In every other case a hold is a refusal.
- The shell jail does not cover Cursor. Cursor's terminal commands are checked and recorded by the hooks, but they do not run in the shell jail.
- The hook calls the agent on port 39393. If you installed with a different
GOLEM_AGENT_PORT, Cursor's hooks cannot reach it. - Project files are not edited. A repository's own
.cursor/hooks.jsonor.cursor/mcp.jsonis left as it is.
The Golem agent also reads Cursor's run mode for the posture report, and a rule can act on it through entry.permission_mode, where Run Everything reads as bypassPermissions.
See also Rules and CEL, Block, hold and contain, Coverage, Limits and Install Golem.