Wire up coding agents

CtxCtl reaches its measured savings only when the agent actually uses it. There are two integration paths, both first-class: expose the five commands as native MCP tools for MCP-native agents, or teach the agent the CLI through a skill. This page covers the setup and the trade-offs; the benchmark data behind them is on Benchmark.

Path 1: native MCP tools

ctxctl mcp is an optional adapter that serves the same five commands as MCP tools over stdio. The CLI stays canonical and unchanged. Add one entry to any MCP client that launches stdio servers:

{
  "mcpServers": {
    "ctxctl": {
      "command": "ctxctl",
      "args": ["mcp"]
    }
  }
}

This generic shape works in opencode, Cursor, Claude Desktop, and other MCP-native clients.

The server exposes exactly five tools:

Tool	Wraps
ctxctl_outline	outline <file>
ctxctl_symbol	symbol <file> --name <s>
ctxctl_read	read <file> --lines N-M
ctxctl_deps	deps <file>
ctxctl_exec	exec <cmd> [--keep <pat>]

Behavior notes that matter to agents:

• Results are plain text with the same saved% metrics as the CLI, wrapped as { content: [{ type: "text", text }] }.
• Failures — missing file, unknown symbol, bad arguments — surface as isError: true results, never protocol errors, so the agent sees a readable message instead of a transport break.
• A ctxctl_exec call whose wrapped command exits non-zero prefixes the text with exit code N.
• Config resolution is identical to the CLI, including --config.

Full protocol details (JSON-RPC framing, error codes, initialize handshake) are on MCP Adapter.

Path 2: CLI + skill

For agents without MCP support — or when you do not want to register a server — install the ctxctl-core skill. The skill teaches the agent the outline / symbol / read / deps / exec workflow as plain shell commands:

# List available skills
npx skills add Xuepoo/ctxctl-skills --list

# Install the core skill for all detected agents
npx skills add Xuepoo/ctxctl-skills --all

# Or use it once without installing
npx skills use Xuepoo/ctxctl-skills --skill ctxctl-core

The CLI itself needs no configuration: every invocation is stateless, and project preferences resolve from .ctxctl/config.toml automatically (see Commands).

Teach the workflow, not just the tools

Whichever path you choose, agents use ctxctl well only if they know when. A short block in your agent instructions (an AGENTS.md, system prompt, or rules file) goes a long way:

Before reading a file whole:

1. ctxctl outline <file> — see what exists
2. ctxctl symbol <file> --name <s> — read only the needed symbol
3. ctxctl read <file> --lines A-B — for ranges outside symbols
4. ctxctl deps <file> — before jumping across files

Wrap verbose commands instead of running them raw:

5. ctxctl exec "<cmd>" --keep '<pattern>'

The bundled ctxctl-core skill encodes exactly this policy, which is why skill-driven arms already save tokens in the benchmark without custom prompting.

Because ctxctl is stateless, nothing needs to be shared or locked between agents, worktrees, or concurrent sessions: two agents exploring different branches parse fresh state on every call, and config resolution walks up from each session’s own working directory.

Which integration to prefer

Prefer native MCP tools when the client supports them. In the scripted-agent benchmark, native tools removed the friction of skill-driven CLI usage and delivered the largest session-cost reduction (−33% versus built-in read/bash); exploring a 96 KB file through tool-driven slices cut uncached input by up to −86%. Tool schemas also make correct usage discoverable without prompt instructions — the agent sees each tool’s input contract at connect time.

Use the CLI + skill when:

• The agent or harness has no MCP client (many sandboxes and CI runners).
• You want zero registration — the skill is one command away and works across agents.
• You are scripting ctxctl yourself in shell pipelines, where the CLI’s exit codes and --json contract are the right interface.

The two paths share the same handlers, output, and config, so switching later costs nothing — a session can even mix both without inconsistency.

Know the trade-off

Tool-heavy ctxctl sessions took roughly 2× wall-clock time in the benchmark: several small tool calls replace one big read. You pay in seconds what you save in dollars and cache pressure. For throwaway scripts that matters little; for long agent sessions it is usually the better trade.

Once wired up, point your agent at Explore unfamiliar code and Compress command output so it uses the tools well, and check Principles for why the outputs stay cache-hot.