Skip to main content
Agent wrapping starts an existing coding agent with local Caveman endpoints, hooks, skills, and recovery tools. Caveman does not replace the agent. The agent still owns its model calls, user interface, permissions, and project workflow.

​
Supported agents

Profiles record tested upstream versions, but upstream CLIs change independently. Run caveman setup to inspect installed support before relying on a profile.

​
Start an agent

Use a named shortcut to launch an agent with Caveman routing:
Arguments after the shortcut are passed through:
Equivalent explicit form:
For an unlisted command, use:
Generic wrapping supplies proxy environment but cannot infer every agent’s native hook or plugin format.

​
Kilo Code specifics

caveman kilocode is an alias for the second binary published by Kilo’s CLI package. Both launch the same kilo profile. CLI wrapping does not reconfigure an already-running Kilo editor extension. Install the verified Kilo CLI version before using either shortcut:
The wrapper confines Kilo’s active providers to the injected caveman provider. An explicit non-Caveman --model/--m/-m, top-level attach, cloud, or roll-call, or run --attach launches directly with a warning. Attached and cloud sessions execute outside Kilo’s local routed process; roll-call deliberately spans models instead of honoring one routed model. Kilo organization and enterprise-managed config loads after inline environment config. When either higher-priority source is active, or account state cannot be verified safely, the wrapper launches Kilo directly instead of claiming proxy confinement or MCP recovery that later policy could override.

​
Qwen Code specifics

Install Qwen Code’s CLI before using its shortcut:
The Qwen profile reads the existing system-settings source named by QWEN_CODE_SYSTEM_SETTINGS_PATH, or the platform enterprise default when the variable is unset:
  • macOS: /Library/Application Support/QwenCode/settings.json
  • Linux: /etc/qwen-code/settings.json
  • Windows: %ProgramData%\qwen-code\settings.json
It deep-merges the selected local or managed OpenAI-compatible route into a temporary file and points Qwen at that overlay. Enterprise policy and unrelated provider settings survive the merge; the source system settings and ~/.qwen/settings.json are not rewritten. The pinned real-CLI route smoke covers Qwen Code 0.22.3 in both local and managed modes.

​
What a profile can change

Profiles are data files compiled by the CLI. A profile can declare:
  • executable name and wire protocol
  • environment or configuration-file injection
  • local proxy endpoint templates
  • supported command and memory hooks
  • skills to install
  • native plugins
  • version and capability notes
The profile compiler rejects unknown keys, unsafe paths, unsupported injection types, reserved command collisions, and unapproved environment templates. Supported protocols are Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, and Gemini GenerateContent.

​
Wrapping modes

​
Compress (default)

Default wrapping mode compresses eligible context locally and can use TOON for smaller structured data. Supported command output may be shrunk; lossy transformations require recovery storage or an equivalent recovery path.

​
Record

Record mode observes local traffic without changing model-visible request bytes. Use it to establish a baseline or troubleshoot an integration.

​
Pixel

Pixel mode can encode text as an image for configured vision-capable models. It is lossy and model-dependent. The selected model must appear in think.pixel.models; Caveman does not assume image compatibility from a model name.

​
Agent-native setup

Claude Code and Codex can use explicit native setup:
Remove it with:
Native setup installs only files needed by that agent. Caveman hooks and plugins keep local state under Caveman directories or agent-owned configuration paths. Review changes before committing dotfiles or project configuration.

​
Recovery during an agent run

Compressed context includes ccr_... handles or typed ccr://... pointers. Agents with the MCP integration can retrieve exact source through a tool call. Operators can retrieve the same source from a terminal:
Install or remove the recovery MCP registration for Qwen with:
The installer preserves sibling entries and refuses to overwrite or remove a Qwen MCP entry it does not own. Wrapped Qwen 0.22 sessions with that owned registration use blocking MCP discovery so recovery is available before the first request. Recovery is local by default. A handle is useful only while its backing store is available.

​
Skill and hook interaction

Response skills change how an agent writes; Engine compression changes context sent to a model. They are separate controls. Hooks can add reminders, expose recovery tools, or compact command output. An installed skill does not prove that request compression is active, and proxy traffic does not prove that a response skill is active. See Skills and hooks for lifecycle and trust boundaries.

​
Troubleshooting

  1. Run caveman status and confirm selected mode.
  2. Run caveman setup and confirm runtime binaries.
  3. Start in --off mode. If failure remains, problem is outside request transformation.
  4. Inspect provider credential variables without printing secret values.
  5. Confirm agent uses local endpoint emitted by profile.
  6. Use installed-version help because upstream profile requirements can change.
If a transform cannot parse input, cannot store recovery data, or cannot produce smaller safe output, Caveman sends original input.

​
Claude Code Remote Control

Claude Code 2.1.196 and later only allows Remote Control when ANTHROPIC_BASE_URL points at api.anthropic.com; its first-party escape hatch does not cover this check. A proxied session therefore cannot start Remote Control. caveman claude --remote-control and caveman wrap claude --remote-control detect the flag (including --remote-control <name> and --remote-control=<name>, and the legacy bare remote-control subcommand) and launch Claude Code directly, uncompressed. --remote-control-session-name-prefix only names auto-generated sessions and does not start Remote Control, so it keeps routing through the proxy. If caveman enable claude has written the route into settings.json, run caveman disable claude before starting a Remote Control session from a plain claude command, then caveman enable claude again afterwards.