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.

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:

npx skills add JuliusBrussee/caveman

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

npx skills add JuliusBrussee/caveman -a codex

Cursor uses the global path:

npx skills add JuliusBrussee/caveman -a cursor -g

Turn it on inside the agent:

/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 covers plugin and extension installs.

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

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:

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

This list is shorter than the skill's list. Check the wrap documentation 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:

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:

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.

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 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:

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 for an agent you write and the gateway guide for an API integration you control.