# Agent Integrations

`gortex install` (once per machine) and `gortex init` (once per repo)
auto-configure Gortex for every AI coding assistant detected on your
machine. Eighteen adapters ship today.

- `gortex install` writes user-level machinery: `~/.claude.json` MCP,
  `~/.claude/skills/gortex-*`, `~/.claude/commands/gortex-*.md`,
  `~/.gemini/antigravity/` Knowledge Items, and user-level hooks.
- `gortex init` writes per-repo machinery: `.mcp.json`, per-agent
  MCP configs (`.cursor/mcp.json`, `.vscode/mcp.json`, …), repo-local
  hooks where supported, per-agent marker-guarded community-routing
  blocks, and `.claude/skills/generated/` per-community SKILL.md.

Run `gortex init doctor` to see what's currently configured. Both
commands accept `--agents=<csv>` to constrain setup and
`--agents-skip=<csv>` to exclude an adapter.

## Adapter matrix

| Name            | What gets written                                                                               | Mode       | Docs link                                                           |
| --------------- | ----------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------- |
| `claude-code`   | `.mcp.json`, `.claude/*`, `CLAUDE.md`, `.claude/skills/generated/*`, `~/.claude/skills/gortex-*`, `~/.claude/commands/gortex-*.md`, `~/.claude.json` | both       | https://docs.claude.com/en/docs/claude-code/overview                |
| `aider`         | `.aiderignore` block, `CONVENTIONS.md` communities block                                        | project    | https://aider.chat/docs/config/aider_conf.html                      |
| `antigravity`   | `~/.gemini/antigravity/mcp_config.json` + Knowledge Item                                        | user       | https://antigravity.google/docs/mcp                                 |
| `cline`         | `cline_mcp_settings.json` (per VS Code / Cursor globalStorage), `.clinerules/gortex-communities.md` | both     | https://docs.cline.bot/mcp/mcp-overview                             |
| `codex`         | `~/.codex/config.toml` (`[mcp_servers.gortex]` + `SessionStart` / Bash + Gortex MCP read-tool `PreToolUse` / Bash `PostToolUse` hooks), `AGENTS.md` communities block | both       | https://developers.openai.com/codex/mcp                             |
| `continue`      | `.continue/mcpServers/gortex.json`, `.continue/rules/gortex-communities.md`                     | project    | https://docs.continue.dev/customize/deep-dives/mcp                  |
| `cursor`        | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json`, `.cursor/rules/gortex-communities.mdc`    | both       | https://docs.cursor.com/en/context/mcp                              |
| `gemini`        | `.gemini/settings.json` or `~/.gemini/settings.json`, `GEMINI.md` communities block             | both       | https://geminicli.com/docs/tools/mcp-server/                        |
| `hermes`        | `~/.hermes/config.yaml` + `profiles/*/config.yaml` (`mcp_servers`), hooks, `~/.hermes/skills/gortex/SKILL.md` | user       | https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp  |
| `kilocode`      | `mcp_settings.json` + `.kilocode/mcp.json`, `.kilocoderules` communities block                  | both       | https://kilo.ai/docs/features/mcp/using-mcp-in-kilo-code            |
| `kimi`          | `.kimi-code/mcp.json` (project) or `~/.kimi-code/mcp.json` + `~/.kimi-code/config.toml` (`UserPromptSubmit` / `PreToolUse` / `Stop` / `SubagentStart` hooks) | both       | https://www.kimi.com/code/docs/en/kimi-code-cli/customization/hooks.html |
| `kiro`          | `.kiro/settings/mcp.json` + steering/hooks or user-level                                        | both       | https://kiro.dev/docs/mcp/configuration                             |
| `oh-my-pi`      | `.omp/mcp.json`                                                                                 | project    | https://github.com/can1357/oh-my-pi/blob/main/docs/mcp-config.md   |
| `opencode`      | `opencode.json` (or existing `opencode.jsonc`), `AGENTS.md` communities block                   | project    | https://opencode.ai/docs/mcp                                        |
| `openclaw`      | `~/.openclaw/openclaw.json` (`mcp.servers.gortex`)                                              | user       | https://docs.openclaw.ai/cli/mcp                                    |
| `pi`            | `.pi/extensions/gortex/index.ts` (project) or `~/.pi/agent/extensions/gortex/index.ts`; `AGENTS.md` communities block only when `--skills` | both | https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md |
| `vscode`        | `.vscode/mcp.json` (`servers` key, 1.102+), `.github/copilot-instructions.md` communities block | project    | https://code.visualstudio.com/docs/copilot/chat/mcp-servers         |
| `windsurf`      | `~/.codeium/mcp_config.json`, `.windsurfrules` communities block                                | both       | https://docs.windsurf.com/plugins/cascade/mcp                       |
| `zed`           | OS-specific `settings.json` (`context_servers`), `.rules` communities block                     | both       | https://zed.dev/docs/ai/mcp                                         |

Mode legend: **project** writes inside the repo (`gortex init` only);
**user** writes under `$HOME` (`gortex install` only); **both** means
the adapter splits: `gortex install` writes the user-level pieces and
`gortex init` writes the repo-level pieces.

Tool-usage guidance (how to prefer graph tools over `Read`/`Grep`) no
longer gets duplicated into every repo. For Claude Code and
Antigravity — the two adapters whose upstream tool exposes a
user-level instructions surface — the guidance lives once per user
(installed by `gortex install`). For the other 13, MCP tool
descriptions carry the teaching. Only codebase-derived community
routing lands in per-repo instructions files.

## Subagent tool propagation

A *subagent* runs in a fresh context window with its own scoped tool
allowlist. Whether a subagent can use Gortex's MCP tools depends
entirely on whether that allowlist names them — a subagent does **not**
automatically inherit every tool the parent has.

- **Claude Code** has a first-class subagent concept with per-subagent
  tool allowlists, and Gortex propagates explicitly. `gortex install`
  writes two subagent definitions to `~/.claude/agents/` —
  `gortex-search` (locate / trace / explore) and `gortex-impact`
  (blast-radius / verification) — each with an explicit
  `tools: mcp__gortex__…` frontmatter listing exactly the graph tools it
  needs. The allowlist is **graph-only by construction**: it contains no
  `Bash`/`Grep`/`Glob`, so a spawned subagent cannot escape the graph.
  A `PreToolUse` Task hook additionally briefs spawned subagents. The
  allowlists are validated in CI (`subagents_test.go`) so a tool rename
  can't silently drop a subagent's access. Programmatic access:
  `claudecode.SubAgentTools(def)` parses an allowlist out of a definition.
- **Session-inheriting hosts** (e.g. `opencode`): subagents inherit the
  *parent's* MCP session at the client level, so they see Gortex tools
  transparently **only if the host propagates the session to the child**.
  This is a client-side behaviour — Gortex configures the MCP server for
  the host but cannot force a client to share its session with a subagent.
- **Hosts with no subagent concept**: the question does not arise; the
  single agent already holds the configured Gortex tools.

If a subagent reports it cannot see `mcp__gortex__*` tools, check the
subagent's own tool allowlist first — that is where propagation is
decided, not the server.

## Common CLI flags

```
# Machine-wide (run once)
gortex install                       # user-level MCP, skills, slash commands, hooks
gortex install --start --track       # also spawn daemon + track current dir
gortex install --agents=claude-code  # constrain to one adapter
gortex install --dry-run --json      # plan-only, JSON report

# Per repo (run in each project)
gortex init                          # interactive: only asks about hooks
gortex init --yes                    # skip prompt, use defaults
gortex init --analyze                # include a richer CLAUDE.md codebase overview
gortex init --no-skills              # skip community-routing generation
gortex init --skills-min-size 5 --skills-max 10
gortex init --agents=claude-code,cursor     # allow-list
gortex init --agents-skip=antigravity       # block-list
gortex init --dry-run --json         # plan, emit JSON report
gortex init --force                  # overwrite merge-preserved keys
gortex init --hooks-only             # refresh supported agent hooks only

# Observe-only
gortex init doctor                   # read-only state report
gortex init doctor --json            # machine-readable report
```

## Adapter contract

Every adapter under `internal/agents/<name>/` implements the
`agents.Adapter` interface:

- `Name()` — stable identifier used by `--agents`
- `DocsURL()` — upstream docs link (for `--json` reports)
- `Detect(env)` — cheap filesystem/`PATH` probe; never writes
- `Plan(env)` — returns the set of files Apply *would* touch,
  without writing
- `Apply(env, opts)` — performs the writes, respecting
  `opts.DryRun` and `opts.Force`

Every write funnels through `agents.WriteIfNotExists`,
`agents.MergeJSON`, or `agents.MergeTOML`. Those helpers provide:

- Atomic temp-file-plus-rename — a partial failure can't leave a
  half-written config
- Uniform dry-run handling — no adapter has its own bool
- Structured `FileAction` results — `--json` and doctor speak the
  same vocabulary
- Malformed-file backup — a user with broken JSON gets a `.bak`
  sibling instead of silent data loss

## Per-agent notes

### claude-code

The primary integration, split across the two commands.

**`gortex install` (user-level, once per machine)** writes:

- `~/.claude.json` — MCP stanza pointing at `gortex mcp`
- `~/.claude/settings.local.json` — user-level Claude Code hooks
  (unless `--no-hooks`)
- `~/.claude/skills/gortex-*/SKILL.md` — curated tool-usage skills
  (`gortex-guide`, `gortex-explore`, `gortex-debug`, `gortex-impact`,
  `gortex-refactor`), one source of truth per user instead of copied
  into every repo
- `~/.claude/commands/gortex-*.md` — slash commands
  (`/gortex-guide`, etc.), also codebase-agnostic and therefore
  user-level

**`gortex init` (per repo)** writes:

- `.mcp.json` — project MCP stanza
- `.claude/settings.json` — MCP permissions merge
  (`mcp__gortex__*` allowlist)
- `.claude/settings.local.json` — repo-local hooks (unless
  `--no-hooks`)
- `CLAUDE.md` — marker-guarded block (`<!-- gortex:communities:start -->`
  / `<!-- gortex:communities:end -->`) carrying the codebase overview
  (via `--analyze`) and the community routing (via `--skills`,
  default on); if neither flag produces content, no block is written
- `.claude/skills/generated/<DirName>/SKILL.md` — one per detected
  community, regenerated each run so the content tracks the graph

Hooks installed today: **PreToolUse**, **PreCompact**, **Stop**,
**SessionStart** — SessionStart fires on new or resumed sessions to
prime the first turn with graph orientation; PreCompact fires on
summary boundaries.

### aider

Aider has no native MCP client today. We install an `.aiderignore`
block telling Aider to skip Gortex's cache dirs so it doesn't waste
tokens ingesting them.

### antigravity

Two artifacts: a native MCP registration at
`~/.gemini/antigravity/mcp_config.json` (new in 2026) plus a
Knowledge Item at `~/.gemini/antigravity/knowledge/gortex-workflow/`
that documents how to use Gortex via `run_command`. The KI stays
because it gives workflow intent the raw MCP registration doesn't.

### cline

Extension ID `saoudrizwan.claude-dev`. We write
`cline_mcp_settings.json` to each VS Code and Cursor globalStorage
directory that exists. Auto-approval field is `alwaysAllow` (not
`autoApprove`, which is a different field in the schema).

### codex

OpenAI Codex CLI stores config in `~/.codex/config.toml`. We
upsert a `[mcp_servers.gortex]` table there. When hooks are enabled
(the default), Codex receives user-level hooks that keep the integration
soft-only: they add graph context or read-shaping guidance without
denying tools, rewriting input, or suppressing output.

Current Codex hook coverage:

| Surface | Coverage |
| ------- | -------- |
| `SessionStart` | Matches `startup|resume|clear|compact` and emits graph-tools orientation for new, resumed, cleared, and compacted sessions. |
| Bash `PreToolUse` | Soft graph guidance for shell search/read/list shapes. |
| Gortex MCP read-tool `PreToolUse` | `read_file` and `get_editing_context` guidance that nudges source reads toward `compress_bodies`. |
| Bash `PostToolUse` | Output graph enrichment for Bash-wrapped grep/search, source-read, and file-list shapes. |
| `gortex init --hooks-only` | Refreshes Codex hooks without rewriting the MCP server config, `AGENTS.md`, or other adapter surfaces. |

We do not install separate Codex `PreCompact` or `PostCompact` hooks
today: Codex ignores plain text stdout for those events, while the
`SessionStart` `compact` source already provides the orientation path
after compaction. We also intentionally do not install `Stop`; Codex
`Stop` can continue a turn, which expands the behavior surface and
should be tracked separately if needed. `apply_patch` remains out of
scope for Codex hooks and should be handled by a dedicated follow-up.

### continue

Continue.dev still accepts JSON block files under
`.continue/mcpServers/` even though its native format is YAML with
metadata headers. We write the JSON form today for zero-dependency
simplicity; upgrading to the YAML+metadata form is tracked.

### cursor

Project-level `.cursor/mcp.json` (written by `gortex init`);
`~/.cursor/mcp.json` (written by `gortex install`). Env key is `env`
(not `environment`). Cursor does not expose a user-level rules
surface, so community-routing lives per-repo at
`.cursor/rules/gortex-communities.mdc` — regenerated each `gortex
init` run so it tracks the current graph.

### gemini

Gemini CLI reads `.gemini/settings.json` (project) and
`~/.gemini/settings.json` (user). Distinct from the antigravity
adapter despite the shared `~/.gemini/` prefix.

### kilocode

Kilo Code is a Cline fork with its own globalStorage key
(`kilocode.kilo`). We write to every candidate globalStorage path
(VS Code + Cursor + Insiders variants) plus `.kilocode/mcp.json`
when a project-level directory exists.

### kimi

Kimi Code CLI keeps MCP servers in `.kimi-code/mcp.json` (project, via
`gortex init`) or `~/.kimi-code/mcp.json` (user, via `gortex install`),
and user-level lifecycle hooks in `~/.kimi-code/config.toml` as a
`[[hooks]]` array. Kimi appends a hook's plain stdout to the model
context on exit 0, so Gortex sends soft guidance as plain text and uses
the documented `hookSpecificOutput.permissionDecision = "deny"` shape
only to block an indexed whole-file read.

Current Kimi hook coverage (all gated to Gortex-enabled projects so the
machine-wide user hook stays inert elsewhere):

| Surface | Coverage |
| ------- | -------- |
| `UserPromptSubmit` | Injects graph symbols relevant to the prompt before the model runs. |
| `PreToolUse` | Redirects native `Read`/`Grep`/`Glob`/`Bash` to graph tools — a hard `deny` for an indexed whole-file read, soft plain-stdout guidance otherwise — plus the `read_file`/`get_editing_context` `compress_bodies` nudge. |
| `Stop` | Runs post-turn diagnostics (changed symbols → test targets, guards, dead code, coverage, contracts) and feeds them back so the agent self-corrects before handoff. |
| `SubagentStart` | Briefs a spawned subagent with `smart_context` results and the tool-swap table so it doesn't default to raw `Read`/`Grep`. |

The diagnostics and briefing hooks reach the daemon over its unix
socket (the hook port's HTTP surface is served only under
`--http-addr`), and every path degrades to a silent no-op when the
payload is malformed, the cwd is outside a Gortex project, or the
daemon is unreachable — so normal Kimi flow is never blocked by the
integration.

### kiro

Workspace `.kiro/settings/mcp.json` + steering/hooks via `gortex
init`; `~/.kiro/settings/mcp.json` via `gortex install` (steering
and hooks are project-scoped in Kiro's runtime so they stay per-repo).
The MCP entry carries `autoApprove` and explicit `disabled: false`
keys Kiro's UI expects.

### opencode

The MCP config is written to a root `opencode.json` (or merged into an
existing `opencode.json` / `opencode.jsonc`) — the files OpenCode
actually reads. It does **not** read `.opencode/config.json`, which
Gortex wrote historically. OpenCode's schema also differs from the
canonical form: top-level `mcp.<name>` (not `mcpServers`), `command` is
an array, env key is `environment`, plus a `$schema` pointer at
`https://opencode.ai/config.json`.

### openclaw

Config lives at `~/.openclaw/openclaw.json`. OpenClaw advertises
JSON5 but accepts strict JSON, which is what we emit. Servers go
under `mcp.servers.<name>`.

### pi

**Pi has no MCP support — by design**, so instead of an `mcpServers`
stanza this adapter ships a self-contained TypeScript extension at
`.pi/extensions/gortex/index.ts` (project) or
`~/.pi/agent/extensions/gortex/index.ts` (global). It registers Gortex's
graph tools natively and re-creates the same read-discipline enforcement
the other agents get (skip it with `--no-hooks`). `GORTEX_TOOLS` selects
the eagerly-registered preset (default `core`), matching the daemon.

The read-discipline rules are injected by the extension at runtime.

**Project-local extensions require a one-time trust confirmation** the
first time Pi opens the repo — nothing the installer can do beyond writing
the file.

### vscode

**Schema changed in 2026.** VS Code's native MCP runtime (1.102+)
uses `{"servers": {...}}`, not the Copilot-Chat legacy
`{"mcpServers": {...}}`. `type` is inferred from `command`
presence, so stdio servers don't need a type field.

### windsurf

**Path changed in 2026.** Current canonical path is
`~/.codeium/mcp_config.json`. The legacy
`~/.codeium/windsurf/mcp_config.json` is left in place unless
`--force` is passed, which removes it as part of the migration.

### zed

Zed calls its MCP registry `context_servers`, not `mcpServers`.
Settings file is platform-specific:

- macOS: `~/Library/Application Support/Zed/settings.json`
- Linux: `~/.config/zed/settings.json`
- Windows: `%APPDATA%\Zed\settings.json`

Each entry takes `source: "custom"` alongside the usual
`command/args/env`.

## Troubleshooting

- **Config file malformed**: If an adapter finds invalid JSON/TOML
  it writes a `.bak` sibling before replacing the file with the
  merged result. Check alongside the original.
- **Hook command points at `/tmp/…`**: `gortex init` heals stale
  ephemeral paths automatically on re-run.
- **"Already configured" but tools missing**: re-run with
  `--force` to overwrite our entries; or delete the `gortex`
  stanza from the config and re-run without `--force`.
- **CI / scripted install**: pass `--yes --json` and parse the
  report.