> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caveman.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Wrap Your Agent with Caveman Endpoints and Hooks

> Start any supported coding agent with Caveman proxy endpoints, hooks, skills, and recovery tools. Profiles handle environment injection and protocol routing.

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

| Agent | Wire protocol | Configuration method | Native extension |
| - | - | - | - |
| Aider | OpenAI Chat Completions | Environment | None |
| Claude Code | Anthropic Messages | Environment | Command and memory hooks, skills |
| Codex | OpenAI Responses | Environment | Command hook, skills |
| Gemini CLI | Gemini GenerateContent | Environment | Before-tool hook |
| Hermes Agent | OpenAI Chat Completions | Environment | Plugin |
| Kilo Code | OpenAI Chat Completions | Inline configuration via environment | None |
| OpenClaw | OpenAI Chat Completions | Configuration file | Plugin |
| OpenCode | OpenAI Chat Completions | Configuration plus environment | Plugin |
| Pi | OpenAI Chat Completions | Native extension | Native extension, skills |
| Qwen Code | OpenAI Chat Completions | Temporary system-settings overlay | None |

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:

```bash theme={"dark"}
caveman claude
caveman codex
caveman gemini
caveman aider
caveman hermes
caveman kilo
caveman qwen
caveman openclaw
caveman opencode
caveman pi
```

Arguments after the shortcut are passed through:

```bash theme={"dark"}
caveman codex --full-auto
```

Equivalent explicit form:

```bash theme={"dark"}
caveman wrap codex --full-auto
```

For an unlisted command, use:

```bash theme={"dark"}
caveman run -- my-agent --flag value
```

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:

```bash theme={"dark"}
npm install -g @kilocode/cli@7.5.6
caveman kilo
```

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:

```bash theme={"dark"}
npm i -g @qwen-code/qwen-code@0.22.3
caveman qwen
```

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

```bash theme={"dark"}
caveman wrap --off claude
```

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

### Pixel

```bash theme={"dark"}
caveman wrap --pixel gemini
```

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:

```bash theme={"dark"}
caveman setup --agent-native claude
caveman setup --agent-native codex
```

Remove it with:

```bash theme={"dark"}
caveman setup --agent-native claude --remove
```

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:

```bash theme={"dark"}
caveman tools retrieve <handle>
```

Install or remove the recovery MCP registration for Qwen with:

```bash theme={"dark"}
caveman tools mcp install qwen --server caveman
caveman tools mcp uninstall qwen --server caveman
```

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](/caveman/skills) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.