Caveman

https://github.com/juliusbrussee/caveman
Admin
Caveman is an AI agent skill that dramatically reduces token usage (by ~75%) by making Claude speak...
Tokens:224,608
Snippets:1,974
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run the quickstart example

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/middleware/typescript/README.md

Install the exact package versions for the alpha middleware and SDK, download the quickstart script, and run it in record, compress, and off modes. The default example makes no provider request and runs a deterministic native model/tool loop against the local runtime.

```sh
npm install --save-exact @caveman-ai/sdk@1.1.0 @caveman-ai/middleware@0.1.0-alpha.2 ai@7.0.94 @ai-sdk/provider@4.0.11 zod@4.4.3
curl -fsSLo quickstart.ts https://docs.caveman.so/examples/middleware/quickstart.ts
DEMO_MODE=record node --experimental-strip-types quickstart.ts
DEMO_MODE=compress node --experimental-strip-types quickstart.ts
DEMO_MODE=off node --experimental-strip-types quickstart.ts
```

--------------------------------

### Install and Run Caveman Quickstart

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/middleware/python/README.md

Install the required SDK and middleware packages, download the quickstart script, and execute it in different demo modes.

```sh
python -m pip install 'caveman-sdk==1.1.0' 'caveman-middleware[langchain]==0.1.0a1' 'langchain==1.4.1' 'langchain-core==1.6.3' 'langgraph==1.2.11'
curl -fsSLo quickstart.py https://docs.caveman.so/examples/middleware/quickstart.py
DEMO_MODE=record python quickstart.py
DEMO_MODE=compress python quickstart.py
DEMO_MODE=off python quickstart.py
```

--------------------------------

### CLI setup and start commands

Source: https://github.com/juliusbrussee/caveman/blob/main/README.md

Install the Caveman CLI globally, run setup, then start the proxy in compress mode. The comment notes that plain 'caveman start' only records, and the proxy binds to 127.0.0.1:8787.

```bash
npm install -g @caveman-ai/cli && caveman setup --install
CAVEMAN_MODE=compress caveman start     # binds 127.0.0.1:8787; plain `caveman start` only records
```

--------------------------------

### Inspect or install runtime components with setup

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/cli-reference.md

Shows setup usage: plain inspection, --install to install components, --json for JSON output, and --agent-native to integrate with a specific agent (claude or codex). Add --remove to an --agent-native command to remove that integration.

```bash
caveman setup
```

```bash
caveman setup --install
```

```bash
caveman setup --json
```

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

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

--------------------------------

### Start supported agents with Caveman

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/agent-wrapping.md

Starts each supported agent with Caveman wrapping. Run `caveman setup` to inspect installed support before relying on a profile.

```bash
caveman claude
caveman codex
caveman gemini
caveman aider
caveman hermes
caveman kilo
caveman qwen
caveman openclaw
caveman opencode
caveman pi
```

--------------------------------

### Install and start Qwen Code CLI with Caveman

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/agent-wrapping.md

Installs Qwen Code's CLI and starts Qwen with Caveman. The Qwen profile reads the existing system-settings source named by `QWEN_CODE_SYSTEM_SETTINGS_PATH`, or the platform enterprise default when the variable is unset. It deep-merges the selected local or managed OpenAI-compatible route into a temporary file and points Qwen at that overlay.

```bash
npm i -g @qwen-code/qwen-code@0.22.3
caveman qwen
```

--------------------------------

### List, preview, and install skills

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/cli-reference.md

List installed skills, preview an external skill before installation, and install a skill from a repository.

```bash
caveman tools skills list
caveman tools skills preview owner/repository
caveman tools skills install owner/repository
```

--------------------------------

### Install and run Caveman proxy CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/README.md

Installs the Caveman CLI globally and runs setup, then starts the proxy for a specific agent. Replace 'claude' with your agent (codex, gemini, aider, kilo, qwen, opencode, hermes, openclaw, pi).

```bash
npm install -g @caveman-ai/cli && caveman setup --install
caveman claude        # or codex · gemini · aider · kilo · qwen · opencode · hermes · openclaw · pi
```

--------------------------------

### Install Caveman CLI globally and run setup

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/install-and-update.md

Installs the CLI globally via npm and runs setup to download and verify the release checksum manifest and signature. Failed verification leaves the candidate binary uninstalled.

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

--------------------------------

### Inspect and install skills and MCP before install

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/cli/README.md

Use these commands to inspect skills and MCP before installing. The skills list command shows available skills, preview shows a specific skill, install installs a suite, and mcp install installs the MCP server.

```sh
caveman tools skills list --json
caveman tools skills preview caveman-evidence-review
caveman tools skills install --suite agent-native --agent codex --no-pixel
caveman tools mcp install codex --server caveman-cloud
```

--------------------------------

### Set up scratch config and launch Claude Code with patched hooks

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/testing-session-modes.md

Creates a scratch Claude Code config directory with patched hooks and a settings.json that wires SessionStart and UserPromptSubmit hooks plus a statusLine command, then launches Claude with CLAUDE_CONFIG_DIR pointing at it. Use this to test the patched hooks without touching your real setup; note that --config-dir does not scope claude plugin install and --only claude would install into your real setup. The caveman-*.js glob copies caveman-config.js and caveman-parse.js, and the tracker silently no-ops if either is missing.

```bash
TESTDIR=~/.claude-cavemantest
mkdir -p "$TESTDIR/hooks"
cp src/hooks/package.json src/hooks/caveman-*.js src/hooks/caveman-statusline.sh "$TESTDIR/hooks/"
NODE=$(command -v node)
cat > "$TESTDIR/settings.json" <<JSON
{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "\"$NODE\" \"$TESTDIR/hooks/caveman-activate.js\"",     "timeout": 5 }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "\"$NODE\" \"$TESTDIR/hooks/caveman-mode-tracker.js\"", "timeout": 5 }] }]
  },
  "statusLine": { "type": "command", "command": "bash $TESTDIR/hooks/caveman-statusline.sh" }
}
JSON
CLAUDE_CONFIG_DIR="$TESTDIR" claude
```

--------------------------------

### Preview install with --dry-run

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Preview what the installer would do without making changes. Use the --dry-run flag to see the actions before actually installing.

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.7.0/install.sh | bash -s -- --dry-run
```

--------------------------------

### Install and start Kilo CLI with Caveman

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/agent-wrapping.md

Installs the verified Kilo CLI version and starts Kilo with Caveman. `caveman kilocode` is an alias for the second binary published by Kilo's CLI package; both launch the same `kilo` profile. CLI wrapping does not reconfigure an already-running Kilo editor extension.

```bash
npm install -g @kilocode/cli@7.5.6
caveman kilo
```

--------------------------------

### Quick start: create and run a new agent

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/agent/README.md

Initializes a new agent project and starts the dev server. Requires Node.js 22.19+ and a provider credential.

```bash
npm create @caveman-ai/agent@latest my-agent
cd my-agent
npm run dev
```

--------------------------------

### Enable Caveman Engine with CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/agent/README.md

Installs the Caveman CLI globally and starts the local engine to enable optimized mode.

```bash
npm i -g @caveman-ai/cli && caveman start
```

--------------------------------

### Run installer directly from GitHub

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/install-and-update.md

Use this command to run the Caveman skill installer directly from GitHub. It detects installed agents and installs only matching integrations.

```bash
npx -y github:JuliusBrussee/caveman
```

--------------------------------

### Manual install steps: clone, dry-run, list, install (bash)

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Use these bash commands to clone the caveman repository and run the installer script directly. The --dry-run flag prints every command without writing anything, --list prints the full agent matrix, and --all installs for everything detected. Requires Node.js to run bin/install.js.

```bash
# Clone the repo
git clone https://github.com/JuliusBrussee/caveman.git
cd caveman

# Preview every command the installer would run
node bin/install.js --dry-run --all

# Inspect the agent matrix
node bin/install.js --list

# Install for everything detected
node bin/install.js --all
```

```powershell
node bin/install.js --only opencode --with-mcp-shrink "'C:\Program Files\nodejs\node.exe' 'C:\MCP servers\server.js' 'C:\data folder\'"
```

--------------------------------

### Install Caveman for Continue

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Continue.

```bash
npx -y github:JuliusBrussee/caveman -- --only continue
```

--------------------------------

### Update CLI and repair binary bundle

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/install-and-update.md

Update the JavaScript CLI through npm and then repair the binary bundle. Run 'caveman setup --install' followed by 'caveman setup'.

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

--------------------------------

### Install agent-native setup for Codex or Claude

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/cli/README.md

Run one of these commands to install native Caveman integration into Codex or Claude Code. The setup writes an MCP command, not an access token, into the agent config. Runtime requests use the existing caveman login credential store and pass through control-api authentication, project scope, RBAC, audit, and tenant isolation.

```sh
caveman setup --agent-native codex
# or
caveman setup --agent-native claude
```

--------------------------------

### Install caveman with curl one-liner (macOS/Linux/WSL/Git Bash)

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

One-line installer for macOS, Linux, WSL, and Git Bash. Pipes the install script directly into bash, which runs it sight-unseen. Auto-detects supported agents, installs presets, and wires hooks. Safe to re-run.

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.7.0/install.sh | bash
```

--------------------------------

### Install Qwen Code and launch through Caveman

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/cli/README.md

Install Qwen Code separately, then launch it via Caveman. Qwen wrapping deep-merges the local or managed OpenAI-compatible route into a temporary system-settings file selected through QWEN_CODE_SYSTEM_SETTINGS_PATH.

```sh
npm i -g @qwen-code/qwen-code
caveman qwen
```

--------------------------------

### Inspect Caveman setup result

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/install-and-update.md

Shows the setup status and JSON output. Required binaries power proxy, Engine, MCP recovery, and memory; browser and tool-catalog shrink binaries are optional.

```bash
caveman setup
caveman setup --json
```

--------------------------------

### Install Caveman for AiderDesk

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for AiderDesk.

```bash
npx -y github:JuliusBrussee/caveman -- --only aider-desk
```

--------------------------------

### Install adapter packages for supported frameworks

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/agent/README.md

Installs the base agent with the exact-pinned adapter for the lane used. Each adapter is optional and must match the pinned version.

```bash
npm install @caveman-ai/agent ai@7.0.43
```

```bash
npm install @caveman-ai/agent @mastra/core@1.55.0
```

```bash
npm install @caveman-ai/agent eve@0.29.2
```

--------------------------------

### Install explorer for current project

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/exploration-and-delegation.md

Installs the FastContext-style explorer agent for the current project. Requires the Caveman CLI.

```bash
cave explore install
```

--------------------------------

### Install caveman with PowerShell one-liner (Windows)

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

One-line installer for Windows PowerShell 5.1+. Pipes the install script directly into iex, which runs it sight-unseen. Auto-detects supported agents, installs presets, and wires hooks. Safe to re-run.

```powershell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.7.0/install.ps1 | iex
```

--------------------------------

### List installed rules with node bin/install.js --list

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Lists what got installed. You should see ~30 rows; detected agents are marked. Anything you wanted but isn't marked means the agent wasn't detected, likely because its binary isn't on PATH.

```bash
node bin/install.js --list
```

--------------------------------

### Install Caveman for OpenHands

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for OpenHands with user scope.

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

--------------------------------

### Install as Plain Pi Package

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/pi-extension/README.md

Install the extension as a regular Pi package using npm. Requires the Caveman CLI and local binaries.

```bash
pi install npm:@caveman-ai/pi
```

--------------------------------

### Install rule files only with --only and --with-init

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Installs rule files only, without Claude hooks. The first command installs for one agent; the second writes rule files into the current repo only, using `--with-init` and multiple `--only` flags. No hooks, no global config, nothing outside the repo.

```bash
node bin/install.js --only cursor
```

```bash
node bin/install.js --with-init --only cursor --only windsurf
```

--------------------------------

### Install @caveman-ai/sdk with npm

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/sdk/typescript/README.md

Commands to create a new directory, initialize a Node.js project, and install the SDK version 1.1.0. Use an .mjs file for the first run; the package does not provide a CommonJS require entrypoint.

```bash
mkdir caveman-ts-example
cd caveman-ts-example
npm init -y
npm install @caveman-ai/sdk@1.1.0
```

--------------------------------

### Install Caveman for Crush

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Crush.

```bash
npx -y github:JuliusBrussee/caveman -- --only crush
```

--------------------------------

### Install and uninstall MCP servers for agents

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/cli-reference.md

Install or remove local Model Context Protocol registrations for detected agents. The commands show installing and uninstalling the `caveman` server for Claude and Qwen. Qwen registration is written to `~/.qwen/settings.json`; Caveman preserves sibling settings and refuses to replace or remove entries not recorded as Caveman-owned.

```bash
caveman tools mcp install claude --server caveman
caveman tools mcp uninstall claude --server caveman
caveman tools mcp install qwen --server caveman
caveman tools mcp uninstall qwen --server caveman
```

--------------------------------

### Install Caveman for Qoder

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Qoder with user scope.

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

--------------------------------

### Install Caveman for Sourcegraph Amp

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Sourcegraph Amp with user scope.

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

--------------------------------

### Example output: feat(api) commit

Source: https://github.com/juliusbrussee/caveman/blob/main/skills/caveman-commit/README.md

Example output for a new endpoint diff. Shows a feat commit with a body explaining the why and a closing reference.

```text
feat(api): add GET /users/:id/profile

Mobile client needs profile data without the full user payload
to reduce LTE bandwidth on cold-launch screens.

Closes #128

```

--------------------------------

### Install Caveman for Windsurf

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Windsurf with user scope.

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

--------------------------------

### Install Caveman middleware and SDK

Source: https://github.com/juliusbrussee/caveman/blob/main/README.md

Installs the middleware and SDK for TypeScript or Python. For TypeScript, add your framework (ai, openai, etc.). For Python 3.13+, swap the extra for your framework.

```bash
npm install @caveman-ai/middleware @caveman-ai/sdk        # TypeScript, plus your framework (ai, openai, …)
```

```bash
pip install 'caveman-middleware[langchain]' caveman-sdk   # Python 3.13+, swap the extra for your framework
```

--------------------------------

### Install Caveman for Qwen Code

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Qwen Code with user scope.

```bash
npx skills add JuliusBrussee/caveman -a qwen-code -g
```

--------------------------------

### Install Caveman for GitHub Copilot

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for GitHub Copilot with repo-wide instructions.

```bash
npx -y github:JuliusBrussee/caveman -- --only copilot --with-init
```

--------------------------------

### Example query and response

Source: https://github.com/juliusbrussee/caveman/blob/main/agents/cavecrew-investigator.md

Example of a query 'where symlink-safe flag write?' and the corresponding output showing grouped results with headers (Defs, Callers, Tests) and totals line.

```plaintext
Defs:
- hooks/caveman-config.js:81 — `safeWriteFlag` — atomic write w/ O_NOFOLLOW
- hooks/caveman-config.js:160 — `readFlag` — paired reader
Callers:
- hooks/caveman-mode-tracker.js:33,87
- hooks/caveman-activate.js:40
Tests:
- tests/test_symlink_flag.js — 12 cases
2 defs, 3 callers, 1 test file.
```

--------------------------------

### Install Caveman for Cline

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Cline with user scope.

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

--------------------------------

### Run quickstart.mjs

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/sdk/typescript/README.md

Command to execute the quickstart.mjs file. A successful call prints the provider's parsed JSON response, including native output and usage fields when present.

```bash
node quickstart.mjs
```

--------------------------------

### Install Caveman for opencode

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for opencode using the local script or npx.

```bash
node bin/install.js --only opencode
```

```bash
npx -y github:JuliusBrussee/caveman -- --only opencode
```

--------------------------------

### Install Caveman for Mistral Vibe

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Mistral Vibe with user scope.

```bash
npx skills add JuliusBrussee/caveman -a mistral-vibe -g
```

--------------------------------

### Install Caveman for Kiro CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Kiro CLI with user scope.

```bash
npx skills add JuliusBrussee/caveman -a kiro-cli -g
```

--------------------------------

### Recovery proof output example

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/agent/README.md

Example output from /prove-recovery showing a successful round-trip recovery with sha256 match. Mismatches print as FAILED (sha256 mismatch) and the plan falls back to the original body.

```text
recovery proof: read_file:big.txt round-trip OK (sha256 match efac7be09c1a)
```

--------------------------------

### Install CLI and launch Claude agent

Source: https://github.com/juliusbrussee/caveman/blob/main/engine/README.md

Install the Caveman CLI globally and launch the Claude agent through the local runtime. Requires Node.js and npm.

```bash
npm i -g @caveman-ai/cli
caveman claude
```

--------------------------------

### Install and run caveman-shrink

Source: https://github.com/juliusbrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/README.md

Install caveman-shrink globally with npm, or run it directly via npx with the upstream MCP server command and its arguments.

```bash
npm install -g caveman-shrink
# or run directly via npx
npx caveman-shrink <upstream-command> [...args]
```

--------------------------------

### Install Caveman for Gemini CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install the Caveman extension via the Gemini CLI.

```bash
gemini extensions install https://github.com/JuliusBrussee/caveman
```

--------------------------------

### Quickstart: send a request with Cave.openai().responses.create

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/sdk/python/README.md

Saves as `quickstart.py`. Creates a `Cave` client with `agent` and `default_workflow`, then calls `cave.openai().responses.create` with a model and input. Handles `HTTPError` and `URLError`/`TimeoutError`. A successful call returns the provider JSON as a Python dictionary, not an HTTP response object.

```python
import json
import os
from urllib.error import HTTPError, URLError
from caveman_cloud import Cave

cave = Cave(
    api_key=os.environ["CAVE_API_KEY"],
    base_url=os.environ["CAVE_BASE_URL"],
    agent="support-agent",
    default_workflow="answer-question",
)

try:
    response = cave.openai(
        upstream_key=os.environ.get("OPENAI_API_KEY"),
    ).responses.create({
        "model": os.environ["CAVE_MODEL"],
        "input": "Explain what a retry loop is in one sentence.",
    })
    print(json.dumps(response, indent=2))
except HTTPError as error:
    raise SystemExit(f"Provider request failed: HTTP {error.code}") from error
except (URLError, TimeoutError) as error:
    raise SystemExit(f"Service connection failed: {error}") from error
```

```bash
python quickstart.py
```

--------------------------------

### Example /caveman-compress invocations

Source: https://github.com/juliusbrussee/caveman/blob/main/skills/caveman-compress/README.md

Example invocations of /caveman-compress on various markdown and text files.

```text
/caveman-compress CLAUDE.md
/caveman-compress docs/preferences.md
/caveman-compress todos.md
```

--------------------------------

### Install explorer for current user

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/exploration-and-delegation.md

Installs the explorer agent for the current user instead of the project. Requires the Caveman CLI.

```bash
cave explore install --user
```

--------------------------------

### Init with --provider openai --no-install

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/create-caveman-agent/README.md

Initializes with the OpenAI provider and skips dependency installation, useful when another tool manages dependencies.

```bash
npm create @caveman-ai/agent@latest my-agent -- --provider openai --no-install
```

--------------------------------

### Install caveman-sdk with virtual environment

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/sdk/python/README.md

Creates a Python 3.13 virtual environment and installs `caveman-sdk==1.1.0`. On Windows, activate with `.venv\Scripts\Activate.ps1` in PowerShell. Use `python -m pip` to target the interpreter running your app.

```bash
mkdir caveman-python-example
cd caveman-python-example
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install caveman-sdk==1.1.0
```

--------------------------------

### Agent-native setup for Claude Code and Codex

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/agent-wrapping.md

These commands enable explicit native setup for Claude Code and Codex. Native setup installs only files needed by that agent, and Caveman hooks and plugins keep local state under Caveman directories or agent-owned configuration paths.

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

--------------------------------

### Pass arguments to Codex with Caveman

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/agent-wrapping.md

Passes arguments after the shortcut through to the wrapped agent. This example starts Codex with the `--full-auto` flag.

```bash
caveman codex --full-auto
```

--------------------------------

### caveman CLI usage examples

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/cli/README.md

Shows common caveman commands: wrapping agents (claude, kilo, qwen), learning, setup, and stats. The claude command is shorthand for 'caveman wrap claude'.

```sh
caveman claude        # shorthand for `caveman wrap claude`; bootstraps signed runtime on first TTY run
caveman kilo          # Kilo Code CLI; `caveman kilocode` works too
caveman qwen          # Qwen Code CLI through a temporary system-settings overlay
caveman learn         # interactive local Setup Score + grouped top moves
caveman setup         # show which companion binaries are installed
caveman stats         # local dashboard: tokens, API estimates, subscription equivalents
```

--------------------------------

### Download and review install.sh before running

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Download the install script first, review it, then run it. This avoids piping a script sight-unseen into a shell. Bootstrap, package, and hook downloads stay pinned to the immutable v2.7.0 release.

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.7.0/install.sh -o install.sh
```

```bash
bash install.sh
```

--------------------------------

### Workflow labeling plan table

Source: https://github.com/juliusbrussee/caveman/blob/main/skills/caveman-discover/SKILL.md

A markdown table presented to the user for approval. Lists each workflow, its purpose, where it is defined (file:line), and how it gets labeled. Example rows show typical projects and note that a job's purpose may be inferred from its filename.

```markdown
| workflow | job | where | how it gets labeled |
|---|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 | defaultHeaders on the reply client |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 | header on the digest client |
| eval-suite (review) | scripts/eval.ts:8 — purpose inferred from filename | scripts/eval.ts:8 | env override at invocation |
```

--------------------------------

### First request with Cave client (quickstart.mjs)

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/sdk/typescript/README.md

JavaScript example that creates a Cave client and sends a request to the OpenAI-compatible responses endpoint. Requires CAVE_API_KEY, CAVE_BASE_URL, and CAVE_MODEL environment variables. Prints the parsed JSON response or an error message.

```javascript
import { Cave } from "@caveman-ai/sdk";

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running this example`);
  return value;
}

const cave = new Cave({
  apiKey: required("CAVE_API_KEY"),
  baseURL: required("CAVE_BASE_URL"),
  agent: "support-agent",
  defaultWorkflow: "answer-question",
  timeoutMs: 30_000,
});

try {
  const response = await cave.openai({
    upstreamKey: process.env.OPENAI_API_KEY,
  }).responses.create({
    model: required("CAVE_MODEL"),
    input: "Explain what a retry loop is in one sentence.",
  });
  console.log(JSON.stringify(response, null, 2));
} catch (error) {
  console.error(error instanceof Error ? error.message : String(error));
  process.exitCode = 1;
}
```

--------------------------------

### Run an agent from code with run()

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/agent/README.md

Runs the agent with a user message and logs the text response and context bill. On a machine with only Node and a provider credential, the run returns `mode: "observe-only"`; with the Caveman runtime installed and started, it returns `mode: "optimized"`.

```TypeScript
import support from "./agent.js";
import { run } from "@caveman-ai/agent";

const result = await run(support, "Can I get a refund?");
console.log(result.text);
console.log(result.contextBill);
```

--------------------------------

### Build from source on Unix

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/install-and-update.md

Clones the repository and runs the platform installer script. Source build uses versions pinned by repository manifests; do not mix old CLI with newer companion binaries.

```bash
git clone https://github.com/JuliusBrussee/caveman.git
cd caveman
./scripts/install-local-cli.sh
```

--------------------------------

### Configure think.core setting

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/cli/README.md

Use these commands to get or set the think.core configuration. Setting think.core to off disables Core changes while compression, recovery, and telemetry continue. Setting it to on re-enables Core. Changes affect later hook events; start a new agent session to clear Core already delivered into model context.

```sh
caveman tools config get think.core
caveman tools config set think.core off
caveman tools config set think.core on
```

--------------------------------

### Install Caveman for Hermes Agent

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Hermes Agent using npx or the local install script.

```bash
npx -y github:JuliusBrussee/caveman -- --only hermes
```

```bash
node bin/install.js --only hermes
```

--------------------------------

### Install Caveman for Oh My Pi (OMP)

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for OMP using npx or the local install script.

```bash
npx -y github:JuliusBrussee/caveman -- --only omp
```

```bash
node bin/install.js --only omp
```

--------------------------------

### Legacy explorer install alias

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/exploration-and-delegation.md

Legacy alias for the explorer installation command. Installs the caveman-explore skill without pixel support.

```bash
caveman tools skills install caveman-explore --no-pixel
```

--------------------------------

### List installer agent matrix with install.sh, install.ps1, or npx

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Run any of these commands to print the live agent matrix from the installer, showing agent id, profile slug, and auto-detection status. The first three require a local clone; the last uses npx without a clone. install.sh and install.ps1 are thin shims forwarding all flags to bin/install.js.

```bash
# Either of these works (install.sh / install.ps1 are thin shims that
# forward all flags to bin/install.js):
bash install.sh --list             # macOS / Linux / WSL, from a local clone
pwsh install.ps1 --list            # Windows / PowerShell, from a local clone
node bin/install.js --list         # any platform, from a local clone
npx -y github:JuliusBrussee/caveman -- --list   # no clone needed
```

--------------------------------

### Install third-party skills via Skills CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/cli/README.md

Install any third-party skill through the official Skills CLI, then store its instruction body as profitable pixel pages automatically. GitHub shorthand, Git/GitLab URLs, direct skill URLs, local paths, and upstream flags pass through unchanged. Caveman forces upstream copy mode when pixelizing, converts only new or changed skills, keeps SKILL.orig.md for byte-exact revert, and reports measured estimated-token reduction as inferred per invocation. --no-pixel keeps upstream plain-text behavior. Third-party instructions and resources are installed as supplied; Caveman does not security-review them. Official Skills CLI telemetry behavior also applies; set DISABLE_TELEMETRY=1 to opt out upstream.

```sh
caveman tools skills add mattpocock/skills --skill tdd --agent codex -y
caveman tools skills add https://github.com/vercel-labs/agent-skills --agent claude-code --global -y
```

--------------------------------

### Connect OpenAI SDK to Gateway

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/deploy.md

Example of initializing the OpenAI client to communicate with the Caveman gateway.

```python
from openai import OpenAI
client = OpenAI(
    base_url="http://caveman.internal:8787/openai/v1",
    api_key="<token>",              # travels as Authorization: Bearer
)
```

--------------------------------

### Install response skill with npx

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/skills-hooks-and-plugins.md

Installs the Caveman response skill using the supported skill installer. Run this command to add the skill to your agent.

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

--------------------------------

### Generate SDK recipes with caveman tools sdk

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/product-model.md

Run these commands to generate copy-ready recipes for integrating the Caveman proxy with provider SDKs. The first command lists SDK recipes, the second lists all snippets, and the third generates a TypeScript OpenAI snippet for the service named my-service.

```bash
caveman tools sdk
caveman snippets
caveman snippets openai-ts --app my-service
```

--------------------------------

### Install Caveman for Antigravity 2.0

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Antigravity 2.0.

```bash
npx -y github:JuliusBrussee/caveman -- --only antigravity-2
```

--------------------------------

### Create a new Caveman agent project

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/sdks-and-packages.md

Initializes a strict starter project for the Agent SDK using the create-caveman-agent initializer. Supports Anthropic, OpenAI, and Google providers. Exactly one detected provider credential selects the provider without prompting; zero or multiple credentials prompt once. Secrets are never printed or written. Use --no-install to skip dependency installation. Generated evaluation begins unapproved and requires review before a locked build.

```bash
npm create @caveman-ai/agent@latest my-agent
cd my-agent
npm run doctor
npm run dev
```

--------------------------------

### Install Caveman for Antigravity IDE

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Antigravity IDE.

```bash
npx -y github:JuliusBrussee/caveman -- --only antigravity
```

--------------------------------

### Go test, vet, and build commands

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/testing-and-benchmarks.md

Runs the Go test suite, vet, and build for the module, covering Engine, proxy, memory, browser bridge, cache planner, rewriter, and other Go packages.

```bash
go test ./...
go vet ./...
go build ./...
```

--------------------------------

### Install Caveman for Warp

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Warp with user scope.

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

--------------------------------

### Install Caveman for Trae

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Trae with user scope.

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

--------------------------------

### Build caveman-browse with Go

Source: https://github.com/juliusbrussee/caveman/blob/main/browse/README.md

Builds the caveman-browse MCP server binary from source using the Go toolchain.

```bash
go build ./browse/cmd/caveman-browse
```

--------------------------------

### First run output in observe-only mode

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/agent/README.md

Shows the console output when running the quick start on a machine without Caveman. Confirms observe-only mode with no transforms or gateway telemetry.

```console
$ npm create @caveman-ai/agent@latest my-agent
$ cd my-agent && npm run dev

  cave: observe-only — engine/gateway unavailable; transforms and gateway
  telemetry off (provider usage and local context estimates remain available)

  agent > what does src/index.ts export?
  … model answers through your own provider credential, direct to the provider …
```

--------------------------------

### Build and run Caveman Gateway

Source: https://github.com/juliusbrussee/caveman/blob/main/proxy/README.md

Commands to build the proxy, serve it on 127.0.0.1:8787 with an Anthropic API key, and print the local spend summary as JSON.

```bash
go build ./proxy/...                 # build
ANTHROPIC_API_KEY=… caveman-proxy    # serve on 127.0.0.1:8787
caveman-proxy stats                  # print the local spend summary as JSON
```

--------------------------------

### Install Caveman for iFlow CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for iFlow CLI.

```bash
npx -y github:JuliusBrussee/caveman -- --only iflow
```

--------------------------------

### Install Caveman for ForgeCode

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for ForgeCode with user scope.

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

--------------------------------

### Install Caveman for Droid

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Droid with user scope.

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

--------------------------------

### Example output of caveman-help

Source: https://github.com/juliusbrussee/caveman/blob/main/skills/caveman-help/README.md

Shows the expected output when the command is run, listing modes, skills, and deactivation triggers.

```text
Modes:
  /caveman              full (default)
  /caveman lite         lighter
  /caveman ultra        extreme
  /caveman wenyan       classical Chinese

Skills:
  /caveman-commit       terse Conventional Commits
  /caveman-review       one-line PR comments
  /caveman-stats        session token savings

Deactivate:
  "stop caveman" or "normal mode"
```

--------------------------------

### Install Caveman for Cursor

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Cursor with user scope.

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

--------------------------------

### Common Commands (npm scripts and Docker)

Source: https://github.com/juliusbrussee/caveman/blob/main/tests/caveman-compress/claude-md-project.original.md

Lists development, testing, database, build, and deployment commands. Includes npm run dev, test, db:migrate, build, lint, typecheck, and docker compose up -d.

```bash
# Development
npm run dev              # Start frontend + backend in parallel
npm run dev:frontend     # Start only Next.js dev server
npm run dev:backend      # Start only Express API server

# Testing
npm run test             # Run unit tests with Vitest
npm run test:watch       # Run tests in watch mode
npm run test:integration # Run integration tests (requires Docker)
npm run test:e2e         # Run Playwright E2E tests

# Database
npm run db:migrate       # Run pending migrations
npm run db:rollback      # Rollback last migration batch
npm run db:seed          # Seed database with sample data
npm run db:reset         # Drop, recreate, migrate, and seed

# Build & Deploy
npm run build            # Build frontend and backend
npm run lint             # Run ESLint on all files
npm run typecheck        # Run TypeScript compiler checks
docker compose up -d     # Start all services locally with Docker
```

--------------------------------

### Install Caveman for OpenClaw

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for OpenClaw using npx.

```bash
npx -y github:JuliusBrussee/caveman -- --only openclaw
```

--------------------------------

### Install Caveman for Devin

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Devin terminal with user scope.

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

--------------------------------

### Install Caveman for JetBrains Junie

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for JetBrains Junie with user scope.

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

--------------------------------

### Build and check commands

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/agent/README.md

Run npm run build to perform a finite search with five seeds per approved fixture. Run npm run check to reject drift before model call. Successful build output includes selected model, reasoning, transform routes, costs, and eval evidence.

```bash
npm run build
npm run check
```

--------------------------------

### Install Caveman for Replit Agent

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Replit Agent from the project Shell.

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

--------------------------------

### Example output table from subagent-tax

Source: https://github.com/juliusbrussee/caveman/blob/main/packages/subagent-tax/README.md

Shows a sample output table listing each harness, its status, wire format, tool and MCP counts, system and schema token sizes, total body size, estimated input tokens, and a variant label. The exact numbers vary per machine and date, with the variant column clarifying what each row measures.

```text
harness       status        wire                    tools  mcp  system  schemas  body  input tokens  variant
------------  ------------  ----------------------  -----  ---  ------  -------  ----  ------------  -------------------------------
claude        ok            anthropic-messages      91     63   42k     219k     267k  ~43k (est)    real config
opencode      ok            openai-responses        10     -    68k     20k      87k   ~14k (est)    isolated config
codex         ok            openai-responses        11     -    40k     10k      52k   ~8.3k (est)   minimal home (floor)
gemini        ok            gemini-generatecontent  8      -    30k     8.3k     39k   ~6.3k (est)   isolated home (api-key mode)
pi            ok            anthropic-messages      4      -    23k     2.8k     26k   ~4.1k (est)   isolated home (4 default tools)
cursor-agent  unmeasurable  -                       -      -    -       -        -     -             -
```

--------------------------------

### Install Caveman for Tabnine CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/INSTALL.md

Install Caveman for Tabnine CLI with user scope.

```bash
npx skills add JuliusBrussee/caveman -a tabnine-cli -g
```

--------------------------------

### Learn from local observations with learn

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/technical/cli-reference.md

Shows learn command variants: basic, filtered by time and sources, --all for comprehensive output, --repo to filter by repository, --json for JSON output, and subcommands implement, apply, simulate, and applied for managing recommendations and fixes. Aider scanning is opt-in via CAVEMAN_AIDER_ROOT.

```bash
caveman learn
```

```bash
caveman learn --since 7d --sources claude,codex,gemini,opencode,aider
```

```bash
caveman learn --all
```

```bash
caveman learn --repo my-project
```

```bash
caveman learn --json
```

```bash
caveman learn implement codex --prompt "focus on config fixes"
```

```bash
caveman learn apply claude_md_weight:project --dry-run
```

```bash
caveman learn simulate claude_md_weight:project recurring_context:abc
```

```bash
caveman learn applied claude_md_weight:project --fix-kind config_trim --note "approved and re-measured"
```

--------------------------------

### Download and run caveman-init via curl

Source: https://github.com/juliusbrussee/caveman/blob/main/commands/caveman-init.md

Download and execute the standalone caveman-init script from the official repository. The script is self-contained and supports stdin execution. Use --dry-run first unless --force is passed.

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/src/tools/caveman-init.js | node - $ARGUMENTS
```
Tokens:
Raw