---
title: "Use Caveman with Claude Code, Codex, Gemini CLI, and other agents"
description: "Caveman has two independent entry points. The skill changes how an agent writes. The local wrapper changes the supported request path so eligible context can be compressed and recovered. Choose the ef"
canonical: https://caveman.so/guides/coding-agent-setup
last-updated: 2026-09-07
---

# Use Caveman with Claude Code, Codex, Gemini CLI, and other agents

Caveman has two independent entry points. The skill changes how an agent writes. The local wrapper changes the supported request path so eligible context can be compressed and recovered. Choose the effect you want, or test both as separate changes.

You keep the agent's interface, model, permissions, and project workflow. The setup should earn its place on a task you can check.

## Install the skill for shorter replies

From the project where you want the skill:

```bash
npx skills add JuliusBrussee/caveman
```

Without the global flag, this installs into the current project's skill location. For Codex:

```bash
npx skills add JuliusBrussee/caveman -a codex
```

Cursor uses the global install path:

```bash
npx skills add JuliusBrussee/caveman -a cursor -g
```

Then activate it in the agent:

```text
/caveman
```

Use `/caveman off` or say “normal mode” to return to normal prose. The skill preserves code, commands, API names, and exact errors. It should step aside when brevity would make an instruction ambiguous.

Cursor skill support does not imply a `caveman cursor` wrap profile. See [the skill documentation](https://docs.caveman.so/docs/skill) for native plugin and extension install options.

## Install the local runtime

```bash
npm install -g @caveman-ai/cli
caveman setup --install
```

The scoped package is Caveman's CLI. `setup --install` installs verified companion binaries needed by the local tools. Keep the underlying coding agent installed and authenticated through its supported path.

Run the profile check before launching:

```bash
caveman doctor claude
caveman claude
```

Use the profile name for the agent you run. A passing check is evidence about that machine and configuration, not every release or credential mode of the host.

## Choose a supported launcher

| Agent | Command | Integration shape |
| --- | --- | --- |
| Claude Code | `caveman claude` | Anthropic Messages through environment |
| Codex CLI | `caveman codex` | OpenAI Responses through environment |
| Gemini CLI | `caveman gemini` | Gemini GenerateContent through environment |
| Aider | `caveman aider` | OpenAI Chat Completions through environment |
| Hermes | `caveman hermes` | OpenAI Chat Completions through environment |
| Kilo Code CLI | `caveman kilo` | Inline provider configuration |
| OpenClaw | `caveman openclaw` | Configuration-file integration |
| OpenCode | `caveman opencode` | Configuration and environment |
| Pi | `caveman pi` | Native extension |
| Qwen Code | `caveman qwen` | Temporary settings overlay |

The profile registry is narrower than skill support. Follow [the current wrap documentation](https://docs.caveman.so/docs/proxy/wrap) for exact host pins and credential limits, especially Kilo and Qwen.

Arguments after the launcher are passed to the host. Preserve your usual permission choices rather than adding more permissive flags for an optimization trial.

## Check mode and recovery

Supported wrappers default to compression. A standalone `caveman start` with no explicit configuration starts in record mode. Inspect the active listener and mode:

```bash
caveman status
caveman setup
```

Some paths need native MCP recovery. The CLI checks for the required binary before advertising that path; missing recovery can cause eligible content to remain uncompressed. See [recovery setup](https://docs.caveman.so/docs/proxy/wrap) and install only the host integration you need.

For Claude Code and Codex, optional native setup is explicit:

```bash
caveman setup --agent-native claude
caveman setup --agent-native codex
```

Choose the command for your host. Inspect generated hooks or plugins before committing dotfiles.

## Run a task that can prove the setup

Use a fresh copy of a small repository with a known task and acceptance test. Run the original agent first, then Caveman in a separate copy of the same starting state.

Include a long tool result with a required detail. Verify that the agent can retrieve the original if the view omits it. Check the final patch or answer rather than relying on the agent's success message.

Inspect local reporting:

```bash
caveman stats
caveman stats --json
```

Count the whole task, including retries and recovery. Keep skill state consistent between arms unless the skill is the change you are evaluating. [The measurement guide](/guides/measure-agent-cost) covers provider usage and subscription limits.

## Diagnose a failed trial

Use pass-through mode to isolate transforms:

```bash
caveman wrap --off claude
```

If the failure remains, inspect the host's endpoint, authentication, tools, and normal behavior. Check credential presence without printing secret values. Confirm the agent is using the endpoint its profile emitted.

If another process owns the local port, do not restart it casually. Use a separate test environment or the original direct launcher. A shared listener may be serving other sessions.

A pass-through result is valid behavior when the content or recovery path is unsupported. It is not evidence of token savings.

## Make the setup a default only after comparison

Keep the wrapper for workflows where accepted tasks improve. Keep direct launch available for diagnosis and unsupported paths. Recheck after host upgrades or configuration changes.

For an agent with no native profile, `caveman run -- my-agent` supplies generic proxy environment but cannot infer every host's hooks, plugins, or protocol. Use [the SDK guide](/guides/agent-sdk-migration) for an application you build and [the gateway guide](/guides/gateway-migration) for a controlled API integration.