---
title: "Set up Caveman with Claude Code, Codex, and Gemini CLI"
description: "Caveman is two installs, not one. The skill makes your agent write shorter replies. The proxy makes the context your agent reads smaller. Almost everyone who says Caveman did nothing installed one of "
canonical: https://caveman.ac/guides/coding-agent-setup
last-updated: 2026-09-19
---

# Set up Caveman with Claude Code, Codex, and Gemini CLI

Caveman is two installs, not one. The skill makes your agent write shorter replies. The proxy makes the context your agent reads smaller. Almost everyone who says Caveman did nothing installed one of them and expected the other.

The constraint behind the whole page: your bill has two halves, input and output, and these two installs touch different halves. Pick the half that hurts, or install both and test them as separate changes.

## The skill shrinks output. The proxy shrinks input.

| | Caveman skill | Caveman proxy |
| --- | --- | --- |
| What it changes | How the model writes back to you | What the model reads before it answers |
| Tokens it touches | Output | Input |
| Install command | `npx skills add JuliusBrussee/caveman` | `npm install -g @caveman-ai/cli` |
| Effect on record | 65% fewer output tokens, measured across 10 prompts | Local byte counts, labelled inferred |
| Account needed | No | No |

Run one, run both, run neither. Neither one depends on the other.

## Install the skill first. It takes about a minute and it is reversible.

From the project where you want it:

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

Without the global flag it installs into the current project. For Codex:

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

Cursor uses the global path:

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

Turn it on inside the agent:

```text
/caveman
```

Say `/caveman off` or "normal mode" to get normal prose back. Code, commands, API names and error text stay byte exact. The skill steps aside when being short would make an instruction ambiguous. Note that installing the skill for Cursor does not give you a `caveman cursor` proxy profile, because those are two different lists. [The skill documentation](https://docs.caveman.so/docs/skill) covers plugin and extension installs.

## Install the proxy when the input side is the part that hurts

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

`setup --install` pulls the companion binaries the local tools need. Keep your coding agent installed and signed in the normal way. Caveman launches it, it does not replace it. Check the profile, then launch:

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

A passing `doctor` is evidence about this machine and this configuration. It is not a promise about every release or credential mode of the host.

## Use the launcher for the agent you already run

| Agent | Command | How it connects |
| --- | --- | --- |
| 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 |

This list is shorter than the skill's list. Check [the wrap documentation](https://docs.caveman.so/docs/proxy/wrap) for host pins and credential limits, Kilo and Qwen especially. Anything you type after the launcher goes straight to the agent. Keep your usual permission flags. Do not loosen them to make a trial run smoother.

## Confirm which mode you are in before you believe any number

Wrapped launchers compress by default. A bare `caveman start` with no configuration records instead. Check which one is live:

```bash
caveman status
caveman setup
```

Some paths need native MCP recovery so the agent can read an original back. The CLI looks for that binary before it offers the path, and without it, content that could have been shrunk is left alone. Claude Code and Codex have an explicit native setup:

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

Read the hooks or plugin files it writes before you commit them to your dotfiles.

## Run one real task twice, in two copies of the same repository

Pick a small repository, a task you have done before, and a test that decides whether the task is done. Copy the starting state twice. Run your normal launcher on the first copy, `caveman claude` on the second.

Make the task pull in one long tool result that hides a detail the answer depends on: a 40,000 token log where the real error is on line 900. That single case tells you whether recovery works. Judge the patch and the test, never the agent's closing summary.

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

Count the whole task, retries and recovery calls included. Keep the skill on, or off, in both arms unless the skill is the thing you are testing. [The measurement guide](/guides/measure-agent-cost) covers provider usage and subscription limits.

## Most failed trials failed for one of these three reasons

**Two changes in one trial.** You added the skill and the proxy in the same hour, replies got shorter, and you credited the proxy. Install one, measure, then install the other.

**Blaming compression for a host problem.** Keep the same path and turn the transforms off:

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

If it still fails, look at the host: endpoint, credentials, tools. Check that credentials exist without printing them.

**A local port that already has an owner.** Another session may be using that listener. Do not restart it to clear the error. Use a separate test environment or launch the agent directly.

A pass-through result is normal behavior when the content or the recovery path is unsupported. It is not a token saving and it is not a bug.

## Make it the default only for workflows that passed

Keep the wrapper where accepted tasks got cheaper or stayed level. Keep the direct launcher for diagnosis and unsupported paths. Recheck after you upgrade the host. For an agent with no profile, `caveman run -- my-agent` hands it proxy environment variables and nothing more, and it cannot guess that host's hooks or protocol. Use [the middleware guide](https://docs.caveman.so/docs/sdk/middleware) for an agent you write and [the gateway guide](/guides/gateway-migration) for an API integration you control.