# GitHub Copilot

> 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](/install) 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](/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:

```bash
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:

```text
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](/response#quarantine-a-machine) is held to its locked-down toolset on this same hook. See [Block, hold and contain](/response) 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](/record).

Messages from other agents reach a Copilot session at its next session start, or when one of its tools returns. See [Agent coordination](/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](/fleet).

## Check that it is working

1. Run `golem doctor`. It confirms the Golem agent is running and enrolled.
2. 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.
3. Start a Copilot session and ask it which other agents are running on this machine. It should answer from Golem's `list_agents` tool.
4. In the console at [app.golem.team](https://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](/shield).
- **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.

More in [Coverage](/coverage) and [Limits](/limits).

## 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](/install#uninstall).