### Start Development Servers

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

Commands to start the frontend and backend development servers. Use `npm run dev` to start both in parallel.

```bash
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
```

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

### Start Docker Services

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

Start all defined services in the Docker Compose configuration in detached mode. Requires Docker to be installed and running.

```bash
docker compose up -d
```

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

### Example PostgreSQL Connection String

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

Example format for the DATABASE_URL environment variable, specifying the PostgreSQL connection details.

```plaintext
postgresql://user:pass@localhost:5432/taskflow
```

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

### Example Redis Connection String

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

Example format for the REDIS_URL environment variable, specifying the Redis connection details.

```plaintext
redis://localhost:6379
```

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

### Install via Claude Plugin

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/index.html

Install the plugin directly through the Claude plugin interface.

```bash
claude plugin install caveman@caveman
```

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

### Example Frontend API URL

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

Example format for the NEXT_PUBLIC_API_URL environment variable, used by the frontend to connect to the backend.

```plaintext
NEXT_PUBLIC_API_URL - Backend API URL for the frontend (e.g., http://localhost:3001)
```

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

### Install Caveman via PowerShell

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

Use this command to install Caveman using PowerShell. It fetches the installation script from a GitHub URL and executes it.

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

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

### Install Caveman via Local Clone

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

Install Caveman from a local clone of the repository using either bash or PowerShell.

```bash
bash hooks/install.sh
```

```powershell
powershell -File hooks\install.ps1
```

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

### Install Caveman for Windsurf

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

Install the Caveman skill for Windsurf via the npx skills command.

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

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

### Install Caveman for Cline

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

Install the Caveman skill for Cline using the npx skills command.

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

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

### Example: Database Connection Pooling (wenyan-full)

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

Use 'wenyan-full' for maximum classical terseness, utilizing classical sentence patterns and omitting subjects where appropriate.

```chinese
池reuse open connection。不每req新開。skip handshake overhead。
```

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

### Install Caveman for Gemini CLI

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

Install the Caveman extension for the Gemini CLI using this command.

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

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

### Example: Database Connection Pooling (wenyan-ultra)

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

Use 'wenyan-ultra' for extreme abbreviation while maintaining a classical Chinese feel, achieving maximum compression.

```chinese
池reuse conn。skip handshake → fast。
```

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

### Install Caveman for Other Agents

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

Use this general command to install the Caveman skill for any other compatible agent.

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

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

### Copy Install Command

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/index.html

Copies a specific CLI command to the clipboard and provides visual feedback on the button.

```javascript
// --- Copy Install --- function copyInstall(btn) { navigator.clipboard.writeText('npx skills add JuliusBrussee/caveman'); btn.textContent = 'Copied'; btn.style.background = 'var(--accent)'; btn.style.color = '#000'; setTimeout(() => { btn.textContent = 'Copy'; btn.style.background = 'var(--text-primary)'; }, 2000); }
```

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

### Example: Database Connection Pooling (lite)

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

Use 'lite' intensity for concise explanations that retain articles and full sentences, suitable for professional communication.

```text
Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead.
```

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

### Example: Database Connection Pooling (ultra)

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

Use 'ultra' intensity for maximum abbreviation, employing arrows for causality and focusing on essential terms.

```text
Pool = reuse DB conn. Skip handshake → fast under load.
```

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

### Install Caveman Plugin

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/index.html

Use the npx command to add the Caveman skill to your environment.

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

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

### Example Compression: Actionable Instruction

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

Illustrates the compression of an actionable instruction, focusing on conciseness by removing politeness, hedging, and redundant phrases, and stating the action directly.

```text
Original:
> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.

Compressed:
> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
```

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

### Example: Database Connection Pooling (full)

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

Use 'full' intensity for classic caveman communication, omitting articles and using short synonyms for brevity.

```text
Pool reuse open DB connections. No new connection per request. Skip handshake overhead.
```

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

### Caveman Review Comment Examples

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

Examples demonstrating the transformation of verbose feedback into the required terse format.

```text
L42: 🔴 bug: user can be null after .find(). Add guard before .email.
```

```text
L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.
```

```text
L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
```

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

### Install Caveman for Claude Code

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

Use this command to install the Caveman plugin for Claude Code from its marketplace.

```bash
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman
```

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

### Example: React Component Re-render (wenyan-lite)

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

Use 'wenyan-lite' for a semi-classical style, dropping filler but retaining grammar structure and a classical register.

```chinese
組件頻重繪，以每繪新生對象參照故。以 useMemo 包之。
```

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

### Install Caveman for Gemini CLI

Source: https://context7.com/juliusbrussee/caveman/llms.txt

Commands to install, update, or uninstall the Caveman extension for the Gemini CLI.

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

# Update
gemini extensions update caveman

# Uninstall
gemini extensions uninstall caveman
```

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

### Caveman Compress Usage Examples

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

Examples of how to use the caveman-compress skill with different file paths. The skill supports .md, .txt, and .rst files, as well as extensionless natural language files.

```bash
/caveman:compress CLAUDE.md
/caveman:compress docs/preferences.md
/caveman:compress todos.md
```

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

### Example: React Component Re-render (lite)

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

Use 'lite' intensity for professional but tight communication, keeping articles and full sentences.

```text
Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`.
```

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

### Install Caveman Compress Plugin

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

The compress skill is included with the caveman plugin. Install caveman once to access the compress skill. Requires Python 3.10+.

```bash
caveman-compress/
```

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

### Example: React Component Re-render (wenyan-ultra)

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

Use 'wenyan-ultra' for extreme abbreviation while maintaining a classical Chinese feel, achieving maximum compression.

```chinese
新參照→重繪。useMemo Wrap。
```

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

### Install Caveman for Copilot

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

Add the Caveman skill to GitHub Copilot using the npx skills command.

```bash
npx skills add JuliusBrussee/caveman -a github-copilot
```

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

### Example: React Component Re-render (wenyan-full)

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

Use 'wenyan-full' for maximum classical terseness, employing classical sentence patterns and omitting subjects where appropriate.

```chinese
物出新參照，致重繪。useMemo .Wrap之。
```

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

### Install Caveman Standalone Hooks (macOS/Linux/WSL)

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

Installs Caveman standalone hooks for macOS, Linux, or WSL environments without using the plugin system. This script configures auto-activation.

```bash
bash <(curl -s https://raw.githubusercontent.com/JuliusBrussee/caveman/main/hooks/install.sh)
```

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

### Install Caveman Plugin for Claude Code

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

Use these commands to install the Caveman plugin and skill for Claude Code. This method includes skills and auto-loading hooks.

```bash
claude plugin marketplace add JuliusBrussee/caveman
```

```bash
claude plugin install caveman@caveman
```

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

### Example JWT Secret

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

Example requirement for the JWT_SECRET environment variable, emphasizing the minimum length for security.

```plaintext
JWT_SECRET - Secret key for signing JWT tokens (minimum 32 characters)
```

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

### Compression Results Example

Source: https://context7.com/juliusbrussee/caveman/llms.txt

A comparison showing the token reduction achieved by applying Caveman compression to a text block.

```text
# Before compression (706 tokens):
"I strongly prefer TypeScript with strict mode enabled for all new code.
Please don't use `any` type unless there's genuinely no way around it,
and if you do, leave a comment explaining the reasoning. I find that
taking the time to properly type things catches a lot of bugs before
they ever make it to runtime."

# After compression (285 tokens):
"Prefer TypeScript strict mode always. No `any` unless unavoidable —
comment why if used. Proper types catch bugs early."

# Average savings: 46% across all file types
```

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

### Install Caveman Hooks (macOS/Linux)

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

Installs Caveman hook files into ~/.claude/hooks/ and patches settings.json to register them. This script is for macOS and Linux systems.

```bash
hooks/install.sh (macOS/Linux) or hooks/install.ps1 (Windows) copies hook files into ~/.claude/hooks/ and patches ~/.claude/settings.json to register SessionStart and UserPromptSubmit hooks plus statusline.
```

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

### Install Caveman for Claude Code

Source: https://context7.com/juliusbrussee/caveman/llms.txt

Commands to install the Caveman plugin or standalone hooks for Claude Code on various operating systems.

```bash
# Plugin installation (recommended)
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

# Or standalone hooks installation (macOS/Linux/WSL)
bash <(curl -s https://raw.githubusercontent.com/JuliusBrussee/caveman/main/hooks/install.sh)

# Windows PowerShell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/hooks/install.ps1 | iex

# Reinstall/update with --force flag
bash hooks/install.sh --force
```

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

### Example: React Component Re-render (full)

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

Use 'full' intensity for classic caveman style, dropping articles and using short synonyms. Fragments are acceptable.

```text
New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.
```

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

### Install Caveman for Cursor

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

Add the Caveman skill to Cursor using the npx skills command.

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

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

### Example Compression: Technical Description

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

Demonstrates how a technical description is compressed by removing filler words, pleasantries, and redundant phrasing while preserving technical terms and structure.

```text
Original:
> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.

Compressed:
> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
```

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

### Add Caveman Skill for Specific Agents

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

Installs the Caveman skill for specific agents like Amp, Augment, Goose, Kiro-cli, and Roo. These commands install the skill file but do not auto-start Caveman.

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

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

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

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

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

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

### Example of Natural Language Compression

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

Demonstrates the transformation of verbose natural language into a concise format, highlighting the removal of filler words and redundant phrasing while maintaining the core message. This illustrates the 'Compress' rules.

```text
Original:
> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.

Compressed:
> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
```

```text
Original:
> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.

Compressed:
> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
```

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

### Install Caveman for Other Agents

Source: https://context7.com/juliusbrussee/caveman/llms.txt

Commands to add the Caveman skill to various AI agents like Cursor, Windsurf, and others via npx.

```bash
# Auto-detect agent
npx skills add JuliusBrussee/caveman

# Specific agent installations
npx skills add JuliusBrussee/caveman -a cursor
npx skills add JuliusBrussee/caveman -a windsurf
npx skills add JuliusBrussee/caveman -a github-copilot
npx skills add JuliusBrussee/caveman -a cline
npx skills add JuliusBrussee/caveman -a amp
npx skills add JuliusBrussee/caveman -a roo

# Windows (if symlinks fail)
npx skills add JuliusBrussee/caveman --copy

# Uninstall
npx skills remove caveman
```

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

### Caveman Full Intensity Example

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

The full Caveman mode provides a significant reduction in tokens, offering a balance between brevity and clarity.

```text
New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.
```

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

### Example: React Component Re-render (ultra)

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

Use 'ultra' intensity for extreme abbreviation, stripping conjunctions and using arrows for causality. One word is used when sufficient.

```text
Inline obj prop → new ref → re-render. `useMemo`.
```

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

### Caveman Token Savings Visualization

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

A visual representation of the benefits of using caveman-compress, highlighting token savings per file, sessions benefited, information preserved, and setup time.

```text
┌────────────────────────────────────────────┐
│  TOKEN SAVINGS PER FILE    █████       46% │
│  SESSIONS THAT BENEFIT     ██████████ 100% │
│  INFORMATION PRESERVED     ██████████ 100% │
│  SETUP TIME                █            1x │
└────────────────────────────────────────────┘
```

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

### Add Caveman Skill with Copy Flag for Windows

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

Installs the Caveman skill using the '--copy' flag, which is recommended for Windows environments where symlinks might fail. This ensures the skill file is copied instead of symlinked.

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

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

### Build Frontend and Backend

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

Compile and bundle the frontend assets and build the backend application for deployment.

```bash
npm run build
```

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

### Run Benchmark with UV

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

Use this command to reproduce benchmark results. Ensure ANTHROPIC_API_KEY is set in your .env.local file.

```bash
uv run python benchmarks/run.py
```

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

### Seed Database with Sample Data

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

Populate the database with initial or sample data. Useful for development and testing environments.

```bash
npm run db:seed
```

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

### Visualize Caveman Hook System Architecture

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

Diagram showing the communication flow between SessionStart and UserPromptSubmit hooks via the .caveman-active flag file.

```text
SessionStart hook ──writes "full"──▶ ~/.claude/.caveman-active ◀──writes mode── UserPromptSubmit hook
                                               │
                                            reads
                                               ▼
                                      caveman-statusline.sh
                                     [CAVEMAN] / [CAVEMAN:ULTRA] / ...
```

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

### Reproduce Benchmark Results

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

Run benchmarks to reproduce token count results. Requires ANTHROPIC_API_KEY in .env.local.

```bash
uv run python benchmarks/run.py
```

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

### Execute Caveman Compression CLI

Source: https://github.com/juliusbrussee/caveman/blob/main/plugins/caveman/skills/compress/SKILL.md

Run the compression script from the directory containing the SKILL.md file.

```bash
cd <directory_containing_this_SKILL.md> && python3 -m scripts <absolute_filepath>
```

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

### Run Caveman Compression Script

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

Execute the compression script from the command line. Ensure you are in the `caveman-compress` directory and provide the absolute path to the file you wish to compress.

```bash
cd caveman-compress && python3 -m scripts <absolute_filepath>
```

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

### Configure Default Caveman Mode

Source: https://context7.com/juliusbrussee/caveman/llms.txt

Set the default activation mode via environment variables or a JSON configuration file.

```bash
# Environment variable (highest priority)
export CAVEMAN_DEFAULT_MODE=ultra
export CAVEMAN_DEFAULT_MODE=lite
export CAVEMAN_DEFAULT_MODE=off  # Disable auto-activation

# Config file: ~/.config/caveman/config.json
{
  "defaultMode": "lite"
}

# Set "off" to disable auto-activation (user can still activate manually)
{
  "defaultMode": "off"
}

# Resolution order: env var > config file > "full" (default)
```

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

### Execute Destructive SQL Operation

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

Example of a destructive operation where Caveman mode is temporarily suspended for clarity.

```sql
DROP TABLE users;
```

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

### Run Evaluation Harness

Source: https://context7.com/juliusbrussee/caveman/llms.txt

Execute evaluation scripts to measure token compression performance.

```bash
# Generate new snapshot (requires claude CLI logged in)
uv run python evals/llm_run.py

# Use smaller model to reduce cost
CAVEMAN_EVAL_MODEL=claude-haiku-4-5 uv run python evals/llm_run.py

# Measure existing snapshot (no API key needed, runs offline)
uv run --with tiktoken python evals/measure.py

# Three-arm comparison:
# __baseline__ - no system prompt
# __terse__    - "Answer concisely."
# <skill>      - "Answer concisely.\n\n{SKILL.md}"
# True skill delta = <skill> vs __terse__
```

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

### Caveman Ultra Intensity Example

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

This ultra-intense mode is for maximum token saving, delivering the core message with extreme brevity.

```text
Inline obj prop → new ref → re-render. `useMemo`.
```

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

### Uninstall Caveman Hooks via Bash

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

Execute this bash command to uninstall Caveman hooks if they were installed using the install.sh script.

```bash
bash hooks/uninstall.sh
```

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

### Caveman Lite Intensity Example

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

This level of Caveman speak is a lighter version, suitable for when you want some reduction but still prefer more explanatory text.

```text
Your component re-renders because you create a new object reference each render. Inline object props fail shallow comparison every time. Wrap it in `useMemo`.
```

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

### Run ESLint

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

Perform static code analysis using ESLint on all project files to check for code style and potential errors.

```bash
npm run lint
```

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

### Run Unit Tests with Vitest

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

Execute unit tests using Vitest. This command is for running tests once.

```bash
npm run test
```

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

### Get Default Caveman Mode

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

Resolves the default Caveman mode from environment variables or configuration files. Defaults to 'full' if no other configuration is found.

```javascript
getDefaultMode()
```

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

### Execute Caveman Compression Script

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

This command navigates to the directory containing the skill's script and executes the Python module to compress a specified file. Ensure you replace `<directory_containing_this_SKILL.md>` and `<absolute_filepath>` with the actual paths.

```bash
cd <directory_containing_this_SKILL.md> && python3 -m scripts <absolute_filepath>
```

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

### Login and Get JWT Tokens

Source: https://github.com/juliusbrussee/caveman/blob/main/tests/caveman-compress/mixed-with-code.md

Use this function to log in with email and password to obtain access and refresh tokens. Ensure Content-Type is set to application/json.

```typescript
const login = async (email: string, password: string) => {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  const { accessToken, refreshToken } = await response.json();
  return { accessToken, refreshToken };
};
```

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

### Caveman Wenyan Mode Example

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

This mode translates the message into classical Chinese (Wenyan), offering a unique and highly condensed way to communicate technical information.

```text
物出新參照，致重繪。useMemo Wrap之。
```

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

### Run Caveman Evaluation Harness

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

Execute the evaluation harness for Caveman using the claude CLI. This helps measure real token compression against a control.

```bash
uv run python evals/llm_run.py
```

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

### Run Pending Database Migrations

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

Apply all pending database migrations to update the database schema to the latest version.

```bash
npm run db:migrate
```

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

### Access Caveman Help Reference

Source: https://context7.com/juliusbrussee/caveman/llms.txt

Display the quick reference card for all available modes, skills, and commands.

```text
# Trigger
/caveman-help
"caveman help"
"what caveman commands"
"how do I use caveman"

# Shows reference card with:
# - All intensity modes (lite/full/ultra/wenyan variants)
# - All skills (commit, review, compress, help)
# - Deactivation commands
# - Configuration options
```

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

### Activate Caveman Mode

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

Writes the active mode to a flag file upon session start using safeWriteFlag. Also emits ruleset and checks for statusline configuration.

```javascript
Runs once per Claude Code session start.
Three things:
1. Writes the active mode to $CLAUDE_CONFIG_DIR/.caveman-active via safeWriteFlag (creates if missing)
2. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user
3. Checks settings.json for statusline config; if missing, appends nudge to offer setup on first interaction

Silent-fails on all filesystem errors — never blocks session start.
```

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

### Run Integration Tests

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

Execute integration tests. This command requires Docker to be running to set up the necessary services.

```bash
npm run test:integration
```

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

### Caveman Compress Process Flow

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

Illustrates the internal process of the caveman-compress skill, including file type detection, compression, validation, and output writing. Only initial compression and targeted fixes consume tokens.

```text
/caveman:compress CLAUDE.md
        ↓
detect file type        (no tokens)
        ↓
Claude compresses       (tokens — one call)
        ↓
validate output         (no tokens)
  checks: headings, code blocks, URLs, file paths, bullets
        ↓
if errors: Claude fixes cherry-picked issues only   (tokens — targeted fix)
  does NOT recompress — only patches broken parts
        ↓
retry up to 2 times
        ↓
write compressed → CLAUDE.md
write original   → CLAUDE.original.md
```

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

### Codex Configuration for Auto-Start

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

This TOML snippet enables Codex hooks, which allows Caveman to auto-activate when running Codex within a local repository. This configuration is typically placed in a `.codex/config.toml` file.

```toml
[features]
codex_hooks = true
```

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

### Refresh Snapshot with Specific Model

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

Runs the evaluation script to refresh the snapshot using a specific, cheaper model like `claude-haiku-4-5`. Requires the `claude` CLI to be logged in.

```bash
CAVEMAN_EVAL_MODEL=claude-haiku-4-5 uv run python evals/llm_run.py
```

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

### Compress Project Memory File

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

Use this command to compress a specified memory file. The original file is backed up and the compressed version is used for subsequent sessions.

```bash
/caveman:compress CLAUDE.md
```

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

### Simulate CLI Interactions

Source: https://github.com/juliusbrussee/caveman/blob/main/docs/index.html

Handles Enter key events to process user input and display simulated terminal output.

```javascript
// --- CLI Interactions --- const cliInput = document.getElementById('cli-input'); const termBody = document.getElementById('termBody'); cliInput.addEventListener('keydown', (e) => { if (e.key === 'Enter' && cliInput.value.trim()) { const val = cliInput.value.trim(); const row = document.createElement('div'); row.className = 'term-line'; row.innerHTML = `<span class="term-accent">❯</span> ${val}`; cliInput.parentElement.before(row); const res = document.createElement('div'); res.className = 'term-line'; res.style.color = 'var(--text-tertiary)'; if (val.toLowerCase() === 'help') res.textContent = "Commands: npx skills add JuliusBrussee/caveman"; else res.textContent = "Input received. Caveman processing... Done. Few words used."; cliInput.parentElement.before(res); cliInput.value = ''; termBody.parentElement.scrollTop = termBody.parentElement.scrollHeight; } });
```