How Caveman Wraps Existing Coding Agents like Claude Code and Codex: A Technical Deep-Dive

Caveman wraps coding agents by launching them unchanged and injecting a local proxy that intercepts their LLM traffic through environment variable redirection, without modifying the agent's source code.

Caveman provides a lightweight wrapper for popular coding agents including Claude Code and Codex. Rather than replacing these tools, it augments them with compression, recording, and MCP tool injection capabilities. This article explains the complete wrapping mechanism based on the JuliusBrussee/caveman source code.

The Core Wrapping Architecture

Caveman's wrapping approach follows a non-invasive proxy pattern. The original agent binary runs untouched—all modifications happen through environment injection and a local traffic interceptor.

The Seven-Step Wrapping Process

1. Profile Resolution – The CLI maps the requested agent ID to a profile containing the binary name, wire protocol, and environment overrides. The supported agents table resides in docs/technical/agent-wrapping.md (lines 9-14).

2. Proxy Initialization – A short-lived Caveman proxy (caveman-proxy) starts on a random localhost port. The CLI reference describes this component as running "one ephemeral wrapped session" (docs/technical/cli-reference.md, lines 16-20).

3. Environment Variable Injection – Before spawning the agent, Caveman rewrites endpoint URLs:

   • Claude Code (Anthropic Messages): ANTHROPIC_BASE_URL → proxy URL
   • Codex (OpenAI Responses): OPENAI_BASE_URL → proxy URL

   This redirection occurs in packages/cli/src/index.ts within wrapRuntimeConfig and the wrap function.

4. MCP Tool Enrichment – The proxy injects five Model-Context-Protocol (MCP) tools (caveman_retrieve, caveman_compress, etc.) into the request's tools array.

5. Hook and Skill Loading – For agents supporting native hooks (Claude Code, Codex), Caveman installs hooks and skills on first run. Installation commands are documented in docs/technical/agent-wrapping.md (lines 48-55).

6. Agent Execution – The binary launches with modified environment. All LLM traffic flows through the local proxy, where Caveman may compress, record, or pixel-encode requests based on the wrap mode.

7. Automatic Cleanup – The proxy exits when the child process terminates, leaving no persistent changes unless caveman enable <agent> was run for permanent native installation.

Environment Injection Implementation

The critical wrapping logic lives in packages/cli/src/index.ts. Before executing the agent binary, Caveman constructs a modified environment object:

• Reads the agent's profile to determine which endpoint variables to override
• Substitutes the official API base URL with the local proxy address
• Preserves all authentication headers and original configuration

This approach works because Claude Code and Codex respect standard environment variables for API endpoint configuration.

Wrap Mode Options

Caveman supports multiple operating modes through CLI flags:

Flag	Behavior
(default)	Full token-wise compression of requests/responses
--off	Recording mode without compression
--pixel	TOON image encoding for vision-capable models

# Standard wrapped session with compression

caveman wrap claude

# Recording mode for Codex

caveman wrap --off codex

# Vision-optimized encoding

caveman wrap --pixel claude

# Generic binary wrapping

caveman wrap my-custom-agent -- --flag value

All commands invoke the same wrap function in packages/cli/src/index.ts.

MCP Tool Injection Details

The proxy automatically appends Caveman's five MCP tools to every request:

• caveman_retrieve – Fetch compressed context from previous sessions
• caveman_compress – Request token-wise compression of large inputs
• caveman_recover – Access recovery data for interrupted sessions
• caveman_record – Trigger diagnostic recording
• caveman_status – Check proxy health and configuration

These tools appear to the agent as standard available functions, requiring zero code changes in the wrapped agent.

Native Hook Integration

For permanent integration, Caveman can install native hooks into Claude Code and Codex:

# Enable persistent Caveman integration

caveman enable claude

This modifies the agent's configuration directory to load Caveman skills automatically. The hook patterns follow the OpenCode plugin structure documented in src/plugins/opencode/README.md and src/plugins/opencode/commands/caveman.md.

Key Source Files

Understanding the wrapping implementation requires examining these files:

• docs/technical/agent-wrapping.md – Architecture overview and supported agents list
• docs/technical/cli-reference.md – caveman wrap command specification
• packages/cli/src/index.ts – Core wrap and wrapRuntimeConfig functions
• packages/cli/src/proxy-fetch.ts – Proxy detection and wrapping eligibility logic
• proxy/README.md and proxy/CLAUDE.md – Traffic forwarding and authentication preservation
• src/plugins/opencode/ – Reference implementation for native hook patterns

Why This Approach Works

Caveman's wrapping strategy succeeds because it exploits standard HTTP client behavior in modern coding agents. Both Claude Code and Codex:

• Accept base URL overrides through environment variables
• Use standard HTTP/HTTPS for LLM communication
• Support tool definitions via MCP or similar protocols
• Load external skills from configurable directories

By operating at the network and environment layer rather than source modification, Caveman remains compatible with agent updates and requires no maintenance of forked code.

Summary

• Caveman wraps coding agents by redirecting their LLM traffic through a local proxy
• Environment injection (ANTHROPIC_BASE_URL, OPENAI_BASE_URL) routes requests without code changes
• The MCP tool array gets enriched with five Caveman-specific functions
• Wrap modes (--off, --pixel) control compression and encoding behavior
• packages/cli/src/index.ts contains the core wrapping implementation
• Native hooks provide permanent integration for Claude Code and Codex

Frequently Asked Questions

Does Caveman modify the Claude Code or Codex source code?

No. Caveman leaves the original agent binaries completely unchanged. It redirects traffic by overriding environment variables before execution and intercepting HTTP requests through a local proxy. The agent operates normally, unaware that its LLM calls route through Caveman's compression and recording layer.

What happens if the Caveman proxy crashes during a session?

The proxy runs as a child process of the CLI wrapper. If it terminates unexpectedly, the agent's subsequent LLM requests will fail to reach the proxy, causing connection errors. However, no data corruption occurs—the agent simply cannot complete LLM calls until restarted without Caveman wrapping.

Can I wrap custom or unofficial coding agents with Caveman?

Yes. The caveman wrap command accepts arbitrary binary names after agent-specific profiles. Use caveman wrap my-custom-agent -- --flag value to launch any executable with Caveman's proxy injected. The generic wrapping assumes standard OpenAI-compatible or Anthropic-compatible HTTP endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}