rtk-ai--rtk/docs/guide/getting-started/supported-agents.md

title, description, sidebar

title	description	sidebar
Supported Agents	How to integrate RTK with Claude Code, Cursor, Copilot, Cline, Windsurf, Codex, OpenCode, Hermes, Kilo Code, Antigravity, and Factory Droid	order 3

Supported Agents

RTK 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 RTK equivalent. The agent runs rtk 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 RTK binary (rtk rewrite). Agent hooks are thin delegates that parse the agent-specific JSON format and call rtk rewrite for the actual decision.

Agent runs "cargo test"
  -> Hook intercepts (PreToolUse / plugin event)
  -> Calls rtk rewrite "cargo test"
  -> Returns "rtk cargo test"
  -> Agent executes filtered command
  -> LLM sees 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 (preToolUse modifiedArgs)	Yes
Cursor	Shell hook (preToolUse)	Yes
Gemini CLI	Rust binary (BeforeTool)	Yes
OpenCode	TypeScript plugin (tool.execute.before)	Yes
OpenClaw	TypeScript plugin (before_tool_call)	Yes
Pi	TypeScript extension (tool_call event)	Yes
Hermes	Python plugin (terminal command mutation)	Yes
Factory Droid	Shell hook (PreToolUse, matcher Execute)	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
Mistral Vibe	Planned (#800)	Pending upstream

Installation by agent

Claude Code

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

Restart Claude Code. Verify:

rtk init --show    # shows hook status

Cursor

rtk init --global --agent cursor

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

GitHub Copilot (VS Code Chat + CLI)

rtk init --copilot            # project-scoped (.github/hooks/)
rtk init --global --copilot   # user-scoped (~/.copilot/hooks/, respects $COPILOT_HOME)

Project-scoped writes .github/hooks/rtk-rewrite.json (both hosts get transparent rewrite — VS Code Chat via updatedInput, Copilot CLI via modifiedArgs) plus the RTK block in .github/copilot-instructions.md. User-scoped writes the same hook config to ~/.copilot/hooks/rtk-rewrite.json and the RTK block to ~/.copilot/copilot-instructions.md (both respect $COPILOT_HOME if set).

Uninstall:

rtk init --uninstall --copilot
rtk init --uninstall --global --copilot

Removes only RTK's hook file (and, for project, the RTK block in copilot-instructions.md). Other files in .github/hooks/ or ~/.copilot/hooks/ and your own instruction content are untouched.

Gemini CLI

rtk init --global --gemini

OpenCode

rtk init --global --opencode

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

Pi

# Project-local (default)
rtk init --agent pi

# Global — all projects
rtk init --agent pi --global

Creates .pi/extensions/rtk.ts (local) or ~/.pi/agent/extensions/rtk.ts (global). Pi auto-discovers extensions from both paths on startup.

Uninstall:

rtk init --uninstall --agent pi
rtk init --uninstall --agent pi --global

Removes only the installed Pi extension file.

OpenClaw

openclaw plugins install ./openclaw

Plugin in the openclaw/ directory. Uses the before_tool_call hook, delegates to rtk rewrite.

Hermes

rtk 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 rtk 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 rtk is missing at load time, the hook is not registered. If rtk 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 rtk rewrite limitations apply: already-prefixed rtk commands, compound shell commands, heredocs, and commands without filters are not rewritten.

Factory Droid

rtk init -g --agent droid    # user-scoped (~/.factory/hooks.json)
rtk init --agent droid       # project-scoped (.factory/hooks.json, commit to share)

Installs a PreToolUse hook (matcher Execute) into Droid's canonical hooks.json — falling back to the hooks key of settings.json only when that file already carries live PreToolUse hooks. Respects $FACTORY_HOME_OVERRIDE.

RTK honors Droid's own permission lists, never another agent's settings. Commands matching an explicit commandDenylist or commandBlocklist entry — read from all four settings scopes (~/.factory/settings.json, ~/.factory/settings.local.json, .factory/settings.json, .factory/settings.local.json) — are left untouched so Droid's native confirmation or block fires on the original command. Every other command is rewritten via updatedInput with no permission decision: Droid's native flow (allowlist, autonomy level, other hooks) decides on the rewritten command. To auto-run rewritten read-only commands, add rtk-prefixed entries (e.g. rtk git status) to your commandAllowlist.

Uninstall:

rtk init --uninstall -g --agent droid
rtk init --uninstall --agent droid

Removes only RTK's hook entry; other hooks and settings are untouched.

Cline / Roo Code

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

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

Windsurf

rtk init --global --agent windsurf    # creates .windsurfrules in current project

Codex CLI

rtk init --codex           # project-scoped (AGENTS.md)
rtk init --global --codex  # user-global (~/.codex/AGENTS.md)

Kilo Code

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

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

Google Antigravity

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

Antigravity reads .agents/rules/ as custom instructions. RTK adds guidance telling Antigravity to prefer rtk <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 rtk <cmd>

Rules file integrations (Cline, Windsurf, Codex, Kilo Code, Antigravity) rely on the model following instructions. Full hook integrations (Claude Code, Cursor, Gemini) are guaranteed — the command is rewritten before the agent sees it. Plugin integrations (OpenCode, Pi) use in-place mutation via the agent's TypeScript extension API.

Windows support

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

• rtk init -g automatically falls back to CLAUDE.md injection mode (prompt-level instructions)
• Filters work normally (rtk cargo test, rtk git status)
• Auto-rewrite does not work — the AI assistant is instructed to use RTK 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 RTK is missing, the hook exits cleanly and the raw command runs unchanged:

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

Override: disable RTK for one command

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

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

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