# Gemini CLI

> Set up Comity hooks, MCP and GEMINI.md instructions for Google's Gemini CLI.

Gemini CLI has its own hook system, so it gets the full integration: hooks on session start, prompts, file writes and shell commands, the Comity MCP server, and a short instructions block in `GEMINI.md`.

## Set up

```sh
cd your-repo
comity init --tools gemini
git add .gemini/settings.json GEMINI.md
git commit -m "Set up Comity for Gemini CLI"
```

Then trust the folder when Gemini CLI asks. Gemini fingerprints project hooks and warns before running new or changed ones: accept the `comity` hooks.

No token is written anywhere and none needs exporting: `comity login` on each machine is enough.

## What init writes

### `.gemini/settings.json`

Six hook events plus the MCP server. Your other settings, hooks and MCP servers are kept; rerunning init replaces only Comity's handlers. Shown for one event:

```json
{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace|run_shell_command",
        "hooks": [
          {
            "name": "comity",
            "type": "command",
            "command": "node -e \"<launcher>\" hook --tool gemini --event BeforeTool",
            "timeout": 5000
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "comity": { "command": "node", "args": ["-e", "<launcher>", "mcp"] }
  }
}
```

| Gemini event | Comity event | Matcher | Timeout (ms) |
|---|---|---|---|
| `SessionStart` | session start | | 5000 |
| `BeforeAgent` | prompt | | 5000 |
| `BeforeTool` | before edit / shell | `write_file\|replace\|run_shell_command` | 5000 |
| `AfterTool` | after edit / shell | `write_file\|replace\|run_shell_command` | 10000 |
| `AfterAgent` | stop | | 10000 |
| `SessionEnd` | session end | | 10000 |

`<launcher>` is a one-line Node script that runs `comity` through the system shell, so the same file works on every OS and in every shell Gemini CLI uses (PowerShell on Windows, `sh` elsewhere). Node must be on `PATH`; the CLI needs it anyway. A hook exits quietly when `comity` isn't installed.

The MCP server is a local stdio process: `comity mcp` relays Gemini's MCP traffic to `https://api.comity.so/mcp` with the token from `comity login` (`COMITY_TOKEN`/`COMITY_SERVER` override it when set). The hooks use the same stored login.

### `GEMINI.md`

A block between `<!-- comity:start -->` and `<!-- comity:end -->` with the [agent instructions](/docs/agents/best-practices). The rest of the file is untouched; rerunning init updates only the block.

## What your agent sees

- **Session start and each prompt**: the briefing as `additionalContext`.
- **Before a write, replace or shell command**: a block returns `decision: "deny"` with Comity's reason, which Gemini sends to the model as the tool error. Warnings are held and delivered with the next prompt or tool result (`BeforeTool` can't add context).
- **After a write, replace or shell command**: new conflicts, messages and answers appended to the tool result.

## Verify

```sh
comity doctor
```

Expect `gemini hooks  all 6 events installed`, `gemini mcp  configured in …/.gemini/settings.json` and `gemini rules  GEMINI.md has the Comity block`. In Gemini CLI, `/hooks panel` lists the `comity` hooks and `/mcp` lists `comity`.

## Limits

- Gemini starts hooks and stdio MCP servers with a sanitized environment that can drop variables such as `COMITY_TOKEN`; both use your stored `comity login`, so log in on each machine.
- Only `write_file`, `replace` and `run_shell_command` are watched. Edits made by MCP tools or extensions aren't seen until Comity diffs the worktree on the next shell command or stop.
- Docs: [Gemini CLI hooks](https://geminicli.com/docs/hooks/), [hooks reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md), [MCP servers](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).