Skip to content

agents.md

Latest commit

 

History

History
416 lines (330 loc) · 22.2 KB

agents.md

File metadata and controls

416 lines (330 loc) · 22.2 KB
Raw

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, UserPromptSubmit, Bash/Gortex-read PreToolUse, and Bash/apply_patch 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 is agent-neutral. Every named MCP connection receives the same mandatory, compact workflow in the server initialization response. Adapters also install that workflow where their host exposes a persistent rules, skill, or extension surface; the wording names only the 21 public tools and the exact gortex call fallback. Codebase-derived community routing still lives in per-repo instruction files because it is workspace-specific.

Compact MCP surface

Every MCP connection with a non-empty clientInfo.name receives the same 21-tool compact surface in hide mode by default. The complete static roster is documented in mcp.md. Empty and pre-initialize sessions retain the server default. Explicit forwarded, operator, or instruction-profile policy wins over the named-client default. Wire-format negotiation is independent, so an unknown named client remains on JSON unless it is separately GCX-capable.

An MCP-capable host MUST call the compact tools directly. In particular, use read({target:{file:"..."}}) for a known source file; it MUST NOT spawn a shell command merely to relay the same request. A harness that exposes Bash but no native Gortex MCP functions MUST use the exact CLI mirror instead:

gortex call read \
  --arg target='{"file":"internal/mcp/server.go"}'

gortex call search \
  --arg operation=symbols \
  --arg query=Server.addTool

The CLI accepts the same compact tool names and argument objects; it does not translate them to legacy names. See the gortex call reference for mutation previews, schema discovery, repository selection, and the distinction between tool dry_run and CLI --dry.

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. The default posture remains advisory. A team can opt into deny, rewrite, or suppress by setting GORTEX_CODEX_HOOK_MODE while running gortex init --hooks-only; the selected posture is written into the managed hook commands.

Current Codex hook coverage:

Surface Coverage
SessionStart Matches `startup
Bash PreToolUse Advises by default; deny hard-blocks graph-detectable fallback reads/searches; rewrite converts only an unambiguous indexed cat <source> into the exact public gortex call read mirror. Compound or ambiguous commands remain advisory.
Gortex MCP read PreToolUse Advises broad file/editing-context reads by default; deny blocks them; rewrite preserves the request and adds options.compress_bodies=true. Selector-driven reads with no explicit operation are covered.
Bash PostToolUse Adds graph context for grep/search, source reads, and conservative file-list shapes: find -name, fd, ls, tree -fi, and git ls-files; bounded sed/awk reads get file graph context. Execution-capable or ambiguous forms are no-ops.
apply_patch PostToolUse Runs detect_changes, extracts affected symbol IDs, then reports tests, guards, and contracts. The completed mutation is never rolled back by the hook.
UserPromptSubmit Re-surfaces prompt-relevant indexed symbols on every turn so long sessions do not rely on the initial reminder alone.
gortex init --hooks-only Refreshes Codex hooks without rewriting the MCP server config, AGENTS.md, or other adapter surfaces.

Postures:

# Existing behavior (default).
GORTEX_CODEX_HOOK_MODE=enrich gortex init --hooks-only

# Enforce graph-detectable fallback reads/searches.
GORTEX_CODEX_HOOK_MODE=deny gortex init --hooks-only

# Rewrite only requests whose semantics can be preserved.
GORTEX_CODEX_HOOK_MODE=rewrite gortex init --hooks-only

# Replace enrichable raw PostToolUse results with graph feedback.
GORTEX_CODEX_HOOK_MODE=suppress gortex init --hooks-only

Current Codex hook behavior implements deny and updatedInput. It does not implement the nominal suppressOutput field; the suppress posture therefore uses the supported PostToolUse result-replacement decision and never emits suppressOutput.

Intentional Codex lifecycle gaps are tracked separately from missing tool coverage:

Surface Intentional status
PreCompact / PostCompact Not installed. SessionStart(source="compact") restores the mandatory workflow after compaction without paying for two more lifecycle hooks.
Stop Not installed. A Stop hook can continue a turn, so adding it is a separate policy decision rather than implicit mutation handling.
Native output-suppression fields Not emitted while Codex rejects suppressOutput and updatedMCPToolOutput; the opt-in suppress posture uses supported PostToolUse result replacement.

apply_patch mutation handling and opt-in deny/rewrite/suppress postures are implemented and are no longer intentional gaps.

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 compact read shaping for broad file/editing-context operations.
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 the same fixed 21 public tools natively through exact gortex call request forwarding and re-creates the same read-discipline enforcement the other clients get (skip it with --no-hooks). It does not expose legacy discovery or depend on dynamic tool promotion.

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.