GitHub Copilot | Golem docs

Connect GitHub Copilot's agent mode to Golem through its hooks and MCP configuration.

There is nothing to configure by hand. When you install Golem on a machine that has Copilot, the Golem agent writes its hooks and MCP servers into Copilot's user configuration. From then on every tool call Copilot's agent makes is checked against your rules before it runs and signed into the record after.

What Golem adds#

One set of files under ~/.copilot serves three Copilot agents: the Copilot CLI (copilot), the Copilot agent in VS Code (which runs the CLI's runtime), and VS Code's older Local agent.

File	What Golem writes
`~/.copilot/hooks/golem.json`	Golem's own hook file, for `sessionStart`, `userPromptSubmitted`, `preToolUse` and `postToolUse`. Each one runs `golem copilot-hook <event>`.
`~/.copilot/mcp-config.json`	Golem's two MCP servers, `golem-witness` and `golem-context`, beside any servers you already have.
`~/.copilot/skills/`	Golem's skills, which the CLI and VS Code both read.

Every other entry in those files is left as it was. Restart the CLI or VS Code after the first install, because Copilot reads hooks and MCP servers at startup.

Each hook command runs only while the golem binary is present. Copilot refuses every tool call whose preToolUse hook fails, so a hook pointing at a deleted binary would otherwise stop all work.

If Copilot is installed after Golem, the Golem agent finds it on its next check (every 15 minutes by default) and wires it then. To wire it straight away, run:

golem setup-client

Copilot asks before every MCP call, Golem's included, and keeps those approvals per repository. Approve Golem's tools the first time Copilot asks in each repository, or for one CLI session with copilot --allow-tool='golem-witness'.

What a block and a hold look like#

A blocked call does not run. Copilot hands the reason to the model, which names the rule and carries a decision id:

blocked by Golem policy (rule "no-force-push-to-main", decision gd_3f9a1c07b2e4d815). Trying again won't change this. If it's a false positive, the user can ask the security team for an exception: golem exception gd_3f9a1c07b2e4d815 --reason "why".

Copilot's hooks have no way to ask a person, so a rule set to Ask cannot become an approval prompt here. What happens depends on who the rule asks:

The rule asks	In Copilot
The person at the keyboard	The call is refused, and the reason says this agent can't ask here. Golem never quietly allows a call it was told to hold.
Your team	The call is refused, and the reason tells the agent your security team decides in the console and to quote the decision id.
Golem's reviewer agent	The call waits while the reviewer decides, for about 35 seconds at most. If no decision has come back yet, the agent is told to wait and retry the same call.

A machine you quarantine is held to its locked-down toolset on this same hook. See Block, hold and contain for the full picture.

What is recorded#

Every tool call before it runs and after it returns, with its arguments. The tool's output is not stored. Copilot's tool names are recorded under the names Claude Code uses for the same tools (bash as Bash, view as Read, create as Write, edit as Edit), so one rule covers both agents.
Each decision Golem made, signed into the session's record.

Messages from other agents reach a Copilot session at its next session start, or when one of its tools returns. See Agent coordination.

The Golem agent also reads how Copilot is set up to run. A CLI session started with --allow-all-tools, --allow-all or --yolo, or VS Code's chat.tools.global.autoApprove turned on, shows under Security Inventory → Agent settings. See Roll out to a fleet.

Check that it is working#

Run golem doctor. It confirms the Golem agent is running and enrolled.
Run golem setup-client. On a wired machine it reports that clients already point at the Golem agent; otherwise it lists the files it changed.
Start a Copilot session and ask it which other agents are running on this machine. It should answer from Golem's list_agents tool.
In the console at app.golem.team, open Conversations. The session appears under the agent copilot.

Limits#

What was said is not recorded. Golem records what the agent did. Your prompts reach the Golem agent only so it can answer with context and messages, and Copilot's hooks carry nothing of the model's replies.
A tool's result cannot be withheld. Copilot ignores a hook's answer after a tool has run, so when a rule on the prompt-injection check would block a result, the result still reaches the model. The verdict is still recorded.
The Copilot cloud agent on github.com is not covered. It reads hooks only from the repository, and its sandbox cannot reach the Golem agent on your machine.
COPILOT_HOME is ignored. The Golem agent runs as a background service and cannot see your shell's environment, so it wires ~/.copilot.
The hooks are written for macOS and Linux shells.
The shell jail does not apply. It covers Claude Code on macOS; Copilot's shell commands run outside it. See Shell jail and sandbox.
If the Golem agent is down, calls run. The hook allows the call rather than stop your work, and nothing is recorded until it is back.

Remove it#

golem setup-client --remove takes Golem's entries out of every AI client on the machine, Copilot included, and remembers the choice so the periodic check does not put them back. To remove Golem entirely, see Uninstall.