Architecture

Caveman's local runtime is a set of small processes joined by documented files, stdio, loopback HTTP, and Model Context Protocol (MCP). Each process owns one boundary so failure can fall back without inventing a result.

Local request path

flowchart TD
    A["Existing coding agent or provider SDK"] -->|"provider request"| P["caveman-proxy on loopback"]
    P --> R["provider route and credential mapping"]
    R --> E["Caveman Engine"]
    E --> C["CCR SQLite store"]
    E -->|"original or recoverable transform"| R
    R --> U["Selected model provider"]
    U -->|"response and usage counters"| P
    P --> D["Local usage SQLite store"]
    P --> A
    M["caveman-mcp in agent"] -->|"retrieve handle"| C

The proxy is a base-URL swap. Agent code and provider request format stay in place. Provider adapters match an allowed route, preserve or resolve the credential, inspect the body, apply enabled transforms, forward upstream, parse usage, and write a local row.

Processes

The JavaScript CLI locates binaries through an explicit CAVEMAN_*_BIN override, then PATH, then ~/.caveman/bin. Missing binaries disable only the commands they power. Wrap is stricter: pointing an agent at a proxy that is absent would break routing, so interactive runs offer a direct launch and non-interactive callers must ensure the proxy is running.

Storage

Default local state lives under ~/.caveman:

Connected CLI state uses ~/.caveman-cloud. Credentials use the macOS Keychain when available, with an owner-only file fallback. Configuration stores pointers and non-secret settings. See security and privacy for deletion and permission details.

Engine boundary

Engine exposes four stable operations:

• Compress: detect, route, transform, count, and persist recovery
• Retrieve: return exact original bytes for a handle
• Detect: classify a payload deterministically
• Stats: aggregate rows stored by CCR

Simulate runs same detector and compressor without storing bytes, then reports whether real compression would require CCR. Its estimate cannot authorize a live transform.

Compressors are pure byte transforms with no access to network, storage, or token accounting. Engine supplies those controls around each compressor.

Recovery paths

Non-streaming API-key requests can use proxy-side handling where supported. Streaming and subscription-auth agent sessions need an agent-side MCP recovery path. The CLI checks that caveman-mcp is present and installed for the selected agent before advertising that path.

A transformed block becomes part of later request prefixes. Caveman stores a deterministic original-to-replacement mapping so the same source block produces the same replacement bytes on later turns. A replacement cache miss or write failure returns original bytes.

Agent-native events

Supported host integrations can send lifecycle events to a user-only Unix socket or Windows named pipe owned by the local proxy. The native runtime normalizes events, records a task contract and decisions, and can move large tool outputs into typed CCR objects.

Session markers are local correlation data. The proxy validates and removes them before provider capture and forwarding. Invalid or ambiguous correlation produces no association.

Failure behavior

Local data-path failures favor correct provider traffic:

Provider errors still reach the caller as provider errors. A transform failure does not become a synthetic success or a client-side parse error.

Source map

• Engine: engine/
• Local proxy and adapters: proxy/
• CLI: packages/cli/
• Recovery MCP: mcp/
• Memory: mem/
• Browser: browse/
• Tool-catalog shrinker: shrink/
• Agent profiles: agents/profiles/
• Public schemas: packages/shared/contracts/