zzet--gortex/docs/agents.md

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
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.