Skip to content

supported-agents.md

Latest commit

 

History

History
186 lines (127 loc) · 7.28 KB

supported-agents.md

File metadata and controls

186 lines (127 loc) · 7.28 KB
Raw
title Supported Agents
description How to integrate contextcrawler with Claude Code, Cursor, Copilot, Cline, Windsurf, Codex, OpenCode, Hermes, Kilo Code, and Antigravity
sidebar
order
3

Supported Agents

contextcrawler supports all major AI coding agents across 3 integration tiers. Mistral Vibe support is planned.

How it works

Each agent integration intercepts CLI commands before execution and rewrites them to their contextcrawler equivalent. The agent runs contextcrawler cargo test instead of cargo test, sees filtered output, and uses up to 90% fewer tokens — without any change to your workflow.

All rewrite logic lives in the contextcrawler binary. The live agent hooks (contextcrawler hook claude / cursor / gemini / copilot) parse the agent-specific JSON payload from stdin and share one rewrite engine for the decision. (contextcrawler rewrite <cmd> exposes the same engine on the command line and is the legacy entrypoint that rules-file integrations and the Hermes/OpenCode plugins call.)

Agent runs "cargo test"
  -> Hook intercepts (PreToolUse / plugin event)
  -> contextcrawler hook <agent> reads the JSON payload
  -> Decides: rewrite to "contextcrawler cargo test"
  -> Agent executes the filtered command
  -> LLM sees up to 90% fewer tokens

Supported agents

Agent Integration tier Can rewrite transparently?
Claude Code Shell hook (PreToolUse) Yes
VS Code Copilot Chat Shell hook (PreToolUse) Yes
GitHub Copilot CLI Shell hook (deny-with-suggestion) No (agent retries)
Cursor Shell hook (preToolUse) Yes
Gemini CLI Rust binary (BeforeTool) Yes
OpenCode TypeScript plugin (tool.execute.before) Yes
Hermes Python plugin (terminal command mutation) Yes
Cline / Roo Code Rules file (prompt-level) N/A
Windsurf Rules file (prompt-level) N/A
Codex CLI AGENTS.md instructions N/A
Kilo Code Rules file (prompt-level) N/A
Google Antigravity Rules file (prompt-level) N/A
Pi (pidev) Rules file (prompt-level) N/A
Mistral Vibe Planned, tracked upstream (rtk#800) Not yet a contextcrawler target

Installation by agent

Claude Code

contextcrawler init --global    # installs hook + patches settings.json

Restart Claude Code. Verify:

contextcrawler init --show    # shows hook status

Cursor

contextcrawler init --global --agent cursor

Restart Cursor. The hook uses preToolUse with Cursor's updated_input format.

VS Code Copilot Chat

contextcrawler init --global --copilot

Gemini CLI

contextcrawler init --global --gemini

OpenCode

contextcrawler init --global --opencode

Creates ~/.config/opencode/plugins/rtk.ts. Uses the tool.execute.before hook.

Hermes

contextcrawler init --agent hermes

Creates ~/.hermes/plugins/rtk-rewrite/ and enables it through plugins.enabled in the Hermes config. Hermes loads Python plugins, so the plugin entrypoint is Python, but it is only a thin adapter. It mutates the Hermes terminal tool command before execution and delegates all rewrite decisions to Rust through contextcrawler rewrite. The repository source and tests for that adapter live in hooks/hermes/; only installed runtime files use the ~/.hermes/plugins/rtk-rewrite/ path.

The plugin fails open. If contextcrawler is missing at load time, the hook is not registered. If contextcrawler rewrite errors, the tool is not terminal, the payload has no string command, or the plugin raises an exception, Hermes runs the original command unchanged. The same contextcrawler rewrite limitations apply: already-prefixed contextcrawler commands, compound shell commands, heredocs, and commands without filters are not rewritten.

Cline / Roo Code

contextcrawler init --agent cline    # creates .clinerules in current project

Cline reads .clinerules as custom instructions. contextcrawler adds guidance telling Cline to prefer contextcrawler <cmd> over raw commands.

Windsurf

contextcrawler init --agent windsurf    # creates .windsurfrules in current project

Codex CLI

contextcrawler init --codex    # creates AGENTS.md or patches existing one

Kilo Code

contextcrawler init --agent kilocode    # creates .kilocode/rules/ctxcrl-rules.md in current project

Kilo Code reads .kilocode/rules/ as custom instructions. contextcrawler adds guidance telling Kilo Code to prefer contextcrawler <cmd> over raw commands.

Google Antigravity

contextcrawler init --agent antigravity    # creates .agents/rules/antigravity-ctxcrl-rules.md in current project

Antigravity reads .agents/rules/ as custom instructions. contextcrawler adds guidance telling Antigravity to prefer contextcrawler <cmd> over raw commands.

Pi (pidev)

contextcrawler init --agent pidev

Installs prompt-level guidance for the Pi coding agent (earendil-works), telling it to prefer contextcrawler <cmd> over raw commands.

Mistral Vibe (planned)

Support is blocked on upstream BeforeToolCallback (mistral-vibe#531). Tracked in #800.

Integration tiers explained

Tier Mechanism How rewrites work
Full hook Shell script or Rust binary, intercepts via agent API Transparent — agent never sees the raw command
Plugin TypeScript, JavaScript, or Python in agent's plugin system Transparent, in-place mutation when the agent allows it
Rules file Prompt-level instructions Guidance only — agent is told to prefer contextcrawler <cmd>

Rules file integrations (Cline, Windsurf, Codex, Kilo Code, Antigravity, Pi) rely on the model following instructions. Full hook integrations (Claude Code, Cursor, Gemini) are guaranteed — the command is rewritten before the agent sees it.

Windows support

The shell hook (rtk-rewrite.sh) requires a Unix shell. On native Windows:

  • contextcrawler init -g automatically falls back to CLAUDE.md injection mode (prompt-level instructions)
  • Filters work normally (contextcrawler cargo test, contextcrawler git status)
  • Auto-rewrite does not work — the AI assistant is instructed to use contextcrawler but commands are not intercepted

For full hook support on Windows, use WSL. Inside WSL, all agents with shell hook integration (Claude Code, Cursor, Gemini) work identically to Linux.

Graceful degradation

Hooks never block command execution. If contextcrawler is missing, the hook exits cleanly and the raw command runs unchanged:

  • contextcrawler binary not found: warning to stderr, exit 0
  • Invalid JSON input: pass through unchanged
  • contextcrawler version too old: warning to stderr, exit 0
  • Filter logic error: fallback to raw command output

Override: disable contextcrawler for one command

CTXCRL_DISABLED=1 git status    # runs raw git status, no rewrite

Or exclude commands permanently in ~/.config/ctxcrl/config.toml:

[hooks]
exclude_commands = ["git rebase", "git cherry-pick"]