---
title: "Switch a Headroom workflow to Caveman"
description: "Start a fresh session when moving a Headroom workflow to Caveman. A Headroom recovery marker belongs to Headroom's store. Caveman cannot resolve it, and there is no documented automatic conversion of "
canonical: https://caveman.so/switch/headroom
last-updated: 2026-09-07
---

# Switch a Headroom workflow to Caveman

Start a fresh session when moving a Headroom workflow to Caveman. A Headroom recovery marker belongs to Headroom's store. Caveman cannot resolve it, and there is no documented automatic conversion of those stored originals into Caveman handles.

This guide covers a wrapped coding agent and a payload-compression pipeline. Keep the old installation until you have finished any sessions that still depend on it.

## Record the current path

Write down the agent command, provider endpoint, Headroom version, and enabled hooks or MCP tools. Note whether Headroom is launched by a wrapper, a background service, or application code.

Check the listener address. Both tools document local proxy use around port 8787. If Headroom occupies that port, finish or move the test session before starting Caveman there. Do not terminate a listener that serves other users just to make the trial fit.

Save the current agent configuration. Keep Headroom's recovery database and any files needed to restore its setup. Those files can contain the original task content, so handle them as you handle the source data itself.

## Replace the launcher for one fresh session

Install Caveman's CLI and its companion binaries:

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

Choose a supported native launcher:

```bash
caveman claude
# Or, for a separate Codex CLI trial:
caveman codex
```

Launch the command directly, without nesting it inside `headroom wrap`. Disable only the Headroom hook or wrapper that belongs to this test configuration. Keep unrelated agent hooks intact.

Caveman's wrapper configures the local provider path and recovery tooling for its supported host. Follow the [wrap reference](https://docs.caveman.so/docs/proxy/wrap) for the current profiles and authentication limits. A bare `caveman start` is a different entry point and defaults to record mode; it is not a substitute for choosing compression deliberately.

## If your application calls a compression library

A library migration needs more than a renamed import. Headroom's return shape and retrieval markers are not Caveman's API. First test the actual payload outside the application's hot path:

```bash
caveman compress < captured-tool-output.json > caveman-view.txt
```

The engine reports accounting separately from the output. Inspect the result and its recovery handle. If no compressor applies, retain that pass-through case in the trial rather than replacing it with a more favorable sample.

For integration, decide whether you want the local proxy around provider requests or the compression engine in your own tool-output pipeline. Your application must preserve the handle, make recovery reachable to the agent, and keep the original store alive for as long as the conversation may need it. Use the [engine reference](https://docs.caveman.so/docs/proxy/engine) for the native interface.

## Prove recovery before checking a percentage

Choose a source payload that includes both repetitive content and a detail the initial question does not need. Ask the agent a second question that requires that detail. Confirm that the answer comes from recovery and agrees with the source.

For a direct byte check, use the real handle emitted by your run:

```bash
caveman retrieve YOUR_RECOVERY_HANDLE > recovered.bin
cmp captured-tool-output.json recovered.bin
```

`YOUR_RECOVERY_HANDLE` is a placeholder, not a usable handle. An empty recovery query returns the original bytes. A query asks for a selected view and should not be used for a byte-for-byte check.

## Compare three arms

Run direct, Headroom, and Caveman against copies of the same starting task. Use the same model and tool permissions. Record the output-shortening skill configuration because the Caveman wrapper can include it in the candidate.

Count all model input and output, recovery turns, retries, and failed attempts. Run the existing correctness checks on the final result. Include at least one short payload where neither compressor has much to remove. Follow [the cost measurement guide](/guides/measure-agent-cost) to report the total outcome.

## Roll back without losing the old context

Close the Caveman test session and restore the saved launcher or hook entry. Restart Headroom using its prior configuration and store if you need to resume an old conversation. Do not copy a Caveman handle into that conversation and expect Headroom to retrieve it.

Remove Caveman-specific test configuration only after no active session uses it. Keep whichever setup wins on the tasks you actually run. The [comparison](/compare/headroom) links the published benchmark and each tool's current recovery documentation.