# https://github.com/JuliusBrussee/caveman Project Manual

Generated at: 2026-06-14 20:35:49 UTC

## Table of Contents

- [Overview and Installation Guide](#page-1)
- [Skills and Behavior System](#page-2)
- [Hooks, Plugins, and MCP Integration](#page-3)
- [Installer and Troubleshooting](#page-4)

<a id='page-1'></a>

## Overview and Installation Guide

### Related Pages

Related topics: [Skills and Behavior System](#page-2), [Installer and Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md)
- [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md)
- [skills/caveman/README.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md)
- [skills/caveman-compress/README.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/README.md)
- [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)
- [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md)
- [src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json)
- [src/mcp-servers/caveman-shrink/compress.js](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js)
- [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)
- [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md)
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md)

</details>

# Overview and Installation Guide

## What Is caveman

caveman is a multi-agent skill pack that conditions coding agents (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, Copilot, and 30+ more) to speak in a terse, compressed prose register while preserving every technical detail exactly. The pitch on the landing page is explicit: cut **~75% of output tokens**, keep full accuracy — "brain still big, mouth small." Source: [README.md:1-3]()

The compressed style drops articles (`a`, `an`, `the`), filler words (`just`, `really`, `basically`), pleasantries, and hedging. It keeps code blocks, inline code, file paths, URLs, commands, and identifiers verbatim. The activation rule itself is short enough to quote: "Respond terse like smart caveman. All technical substance stay. Only fluff die." Source: [src/rules/caveman-activate.md:1-9]()

Six intensity levels ship with the pack: `lite` (drop filler only), `full` (default — drop articles, fragments OK), `ultra` (bare fragments, abbreviations, arrows for causality), and three `wenyan` registers (`wenyan-lite`, `wenyan-full`, `wenyan-ultra`) that render Classical Chinese compression with up to 80–90% character reduction. An auto-clarity rule silently drops back to normal prose for security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity risks misread, and when the user repeats a question. Source: [skills/caveman/README.md:1-25]()

## Skill Pack and Agent Distribution

The repo is a polyglot pack of independent skills. Each skill carries its own `SKILL.md` with `name` and `description` frontmatter so it loads in isolation, without dragging in the rest of the pack. Source: [CLAUDE.md:1-1]()

| Skill | Purpose |
|-------|---------|
| `caveman` | Activates the terse prose mode via `/caveman [lite\|full\|ultra\|wenyan]` |
| `caveman-compress` | Off-line compressor for memory files (`CLAUDE.md`, todos, preferences) — saves input tokens |
| `caveman-commit` | Conventional Commits generator, subject ≤50 chars, imperative mood |
| `cavecrew` | Subagent delegation guide — `cavecrew-investigator`, `cavecrew-builder`, `cavecrew-reviewer` |
| `caveman-shrink` | MCP proxy that compresses prose fields of MCP tool descriptions at runtime |

Source: [skills/caveman/README.md:1-2](), [skills/caveman-compress/README.md:1-4](), [skills/caveman-commit/SKILL.md:1-4](), [skills/cavecrew/SKILL.md:1-25](), [src/mcp-servers/caveman-shrink/package.json:1-7]().

The `caveman-shrink` MCP server is implemented in pure Node so the proxy stays single-runtime. It mirrors the Python `caveman-compress` boundaries — fenced code blocks, inline code, URLs, filesystem paths, and code-looking tokens are NEVER touched; everything else loses filler, hedging, pleasantries, and leading "I'll"/"you can"/"we will" prefixes. Source: [src/mcp-servers/caveman-shrink/compress.js:1-25]()

Distribution to each agent uses a different mechanism but ships the same always-on ruleset. Claude Code gets a plugin plus a `SessionStart` hook that injects rules. Codex gets the same plugin plus `.codex/hooks.json` and `.codex/config.toml`. Gemini CLI receives an extension with a `GEMINI.md` context file. opencode gets a native plugin copied into `~/.config/opencode/plugins/caveman/`, an `AGENTS.md` ruleset, and skills/agents/commands directories; its plugin wires `session.created` and `tui.prompt.append` lifecycle hooks. OpenClaw receives a workspace skill at `~/.openclaw/workspace/skills/caveman/SKILL.md` (frontmatter merged with `version` + `always: true`) plus a marker-fenced bootstrap block in `~/.openclaw/workspace/SOUL.md`, both routed through `bin/lib/openclaw.js`. Source: [CLAUDE.md:1-1]()

Per-agent command files live under `src/plugins/<agent>/commands/`. The opencode caveman-compress command, for example, is defined at [src/plugins/opencode/commands/caveman-compress.md:1-4]() and rejects source/config files (`.py`, `.js`, `.ts`, `.json`, `.yaml`, `.toml`, `.sh`, etc.) — only `.md`, `.txt`, `.typ`, `.tex`, and extensionless prose.

## Installation

The canonical entry point is the npm installer:

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

The same installer powers `npx skills add JuliusBrussee/caveman -a <agent>`, which is the path IBM Bob users follow per [issue #523](https://github.com/JuliusBrussee/caveman/issues/523). For shell-only hosts there are two pinned installers — `install.sh` (`curl|bash`) and `install.ps1` (`irm | iex`). As of v1.9.0 both downloads are pinned + integrity-checked: hook files fetch from the immutable `v1.9.0` tag (not the moving `main` branch) and verify every hook against `src/hooks/checksums.sha256` (SHA-256) before execution; mismatch aborts the install. Source: [CLAUDE.md:1-1](), [README.md:1-3]().

The npm publish itself is gated by the `package.json` `files` array. Contributors adding a new top-level directory the installer needs to ship must edit that array — files outside it never reach npm. Source: [CONTRIBUTING.md:1-1]()

Two invariants from `CONTRIBUTING.md` are worth internalising before debugging or extending the installer. Hooks must silent-fail on filesystem errors: a throwing hook blocks Claude Code session start, which is user-facing breakage. Settings.json reads and writes must go through `bin/lib/settings.js`, which tolerates JSONC comments — direct `JSON.parse` on a user's `settings.json` will crash on a single `// comment`. Source: [CONTRIBUTING.md:1-1]()

## Known Failure Modes

Five recurring installation bugs show up across community threads:

1. **opencode ENOENT for `caveman-compress.md`** — the installer copies a command file that does not exist in the published package ([#367](https://github.com/JuliusBrussee/caveman/issues/367), [#426](https://github.com/JuliusBrussee/caveman/issues/426), [#464](https://github.com/JuliusBrussee/caveman/issues/464), [#482](https://github.com/JuliusBrussee/caveman/issues/482)).
2. **opencode plugin hooks do not fire** — `session.created` and `tui.prompt.append` are not valid opencode hook keys, so the plugin never activates past the first prompt ([#418](https://github.com/JuliusBrussee/caveman/issues/418), [#16](https://github.com/JuliusBrussee/caveman/issues/16)).
3. **PowerShell 7 installer fails** — `irm | iex` errors with `Cannot overwrite variable Args because the variable has been optimized` ([#366](https://github.com/JuliusBrussee/caveman/issues/366)).
4. **Gemini CLI extension fails to load** — invalid agent frontmatter and invalid TOML surface three loader errors against the Gemini extension schema ([#325](https://github.com/JuliusBrussee/caveman/issues/325)).
5. **`caveman-shrink` MCP starts without an upstream** — `claude mcp add caveman-shrink -- npx -y caveman-shrink` registers the server but no upstream command, so it fails on every session load ([#474](https://github.com/JuliusBrussee/caveman/issues/474)).

A security note from [issue #528](https://github.com/JuliusBrussee/caveman/issues/528): the Hermes scanner flags `caveman` as "Caution" for high-risk exfiltration and medium-risk path traversal — operators running it through Hermes should review the MCP proxy path before deployment.

## See Also

- [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) — agent-by-agent distribution matrix and code style invariants
- [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md) — public landing page and benchmark headlines
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md) — PR conventions and `package.json` `files` rules
- [src/mcp-servers/caveman-shrink/](https://github.com/JuliusBrussee/caveman/tree/main/src/mcp-servers/caveman-shrink) — MCP proxy implementation
- [skills/caveman-compress/](https://github.com/JuliusBrussee/caveman/tree/main/skills/caveman-compress) — file compressor source

---

<a id='page-2'></a>

## Skills and Behavior System

### Related Pages

Related topics: [Overview and Installation Guide](#page-1), [Hooks, Plugins, and MCP Integration](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [skills/caveman/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)
- [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)
- [skills/caveman-review/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md)
- [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md)
- [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md)
- [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)
- [AGENTS.md](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md)
- [GEMINI.md](https://github.com/JuliusBrussee/caveman/blob/main/GEMINI.md)
- [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md)
- [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md)
- [src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json)

</details>

# Skills and Behavior System

## Overview

Caveman distributes behavior through independent **skills** — Markdown files with YAML frontmatter — rather than a single monolithic system prompt. Each skill is a self-contained unit that a host agent loads on demand to perform one job: terse response compression, terse commit messages, terse code review, in-place file compression, or subagent delegation guidance. The `skills/` directory is the **single source of truth**; the unified installer in `bin/install.js` mirrors these files into provider-specific locations (Claude Code, Codex, Gemini CLI, opencode, OpenClaw) and copies lightweight ruleset stubs (`AGENTS.md`, `GEMINI.md`) to the project root so they auto-discover on every session Source: [CLAUDE.md:1-50]().

Skills are activated by three mechanisms: explicit slash commands (e.g. `/caveman`), natural-language triggers declared in each skill's `description` frontmatter, and provider-specific lifecycle hooks (Claude Code `SessionStart`, opencode `session.created` / `tui.prompt.append`). Independent frontmatter lets a host load only the skills relevant to the current request rather than pulling every rule into every prompt Source: [CLAUDE.md:1-50]().

## Skill Catalog

The repository ships seven skills, each with a `SKILL.md` (LLM-facing instructions) and a `README.md` (human-facing docs):

| Skill | Role | Activation | Source of truth |
|-------|------|------------|-----------------|
| `caveman` | Core terse-response behavior with six intensity levels | `/caveman` (lite / full / ultra / wenyan) or passive load via `AGENTS.md` | [skills/caveman/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) |
| `caveman-commit` | Conventional Commits message generator (≤50 char subject) | `/caveman-commit` or "write a commit" / "commit message" | [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md) |
| `caveman-review` | One-line code-review comments in `L<line>: <severity>` format | `/caveman-review` or code-review trigger | [skills/caveman-review/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-review/SKILL.md) |
| `caveman-compress` | Compresses `.md` / `.txt` / `.typ` / `.tex` memory files in place; refuses source/config files | `/caveman-compress FILEPATH` or "compress memory file" | [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) |
| `cavecrew` | Subagent delegation guide with strict output contracts | Loaded when the main thread dispatches subagents | [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md) |
| `caveman-help` / `caveman-stats` | Usage help and session-level token statistics | Slash commands | [CLAUDE.md:1-50]() |

Skill boundaries are enforced by what each `SKILL.md` does **not** claim. For example, `caveman-compress` explicitly refuses to compress existing `*.original.md` backups or source/config files such as `.py`, `.js`, `.ts`, `.json`, `.yaml`, `.toml`, `.sh` Source: [src/plugins/opencode/commands/caveman-compress.md:1-19]().

## Behavior Contracts

### Caveman Core Behavior

The behavioral contract is encoded in [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) and surfaced to users in [skills/caveman/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md). The system strips grammatical scaffolding while preserving every technical token:

- **Remove** articles (`a` / `an` / `the`), filler (`just` / `really` / `basically` / `actually` / `simply` / `essentially` / `generally`), pleasantries, and hedging Source: [src/rules/caveman-activate.md:1-15]().
- **Keep exact** every code block, inline code, URL, file path, command, error string, identifier, and markdown structure Source: [src/plugins/opencode/commands/caveman-compress.md:1-19]().
- **Pattern** — `[thing] [action] [reason]. [next step].` — short fragments and short synonyms are preferred Source: [src/rules/caveman-activate.md:1-15]().

Six intensity levels are exposed: `lite` (drop filler only, sentences intact), `full` (default — drop articles, fragments OK), `ultra` (bare fragments with abbreviations and arrow causality), and three Classical Chinese registers (`wenyan-lite`, `wenyan-full`, `wenyan-ultra`) reaching 80–90% character reduction Source: [skills/caveman/SKILL.md:1-30]().

An **Auto-Clarity rule** suspends compression for security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity could cause misreads, and user-repeated questions; the agent resumes terse output after the clear block Source: [src/rules/caveman-activate.md:1-15](). A hard boundary protects code, commit messages, and PR descriptions — those are written in normal prose regardless of mode Source: [src/rules/caveman-activate.md:1-15]().

### Cavecrew Subagent Delegation

`cavecrew` is the dispatching skill: it tells the main thread when to delegate to compressed subagents and when to stay in-line. It pins three subagent roles — `cavecrew-investigator` (read-only search), `cavecrew-builder` (write/edit), and `cavecrew-reviewer` (code review) — each with a strict **output contract** that keeps tokens low by being grep-friendly:

- `cavecrew-investigator` returns `path:line — symbol — short note` lists or the terminal token `No match.` Source: [skills/cavecrew/SKILL.md:1-50]().
- `cavecrew-builder` returns `path:line-range — change ≤10 words` plus a `verified:` line, or one of the terminal tokens `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` Source: [skills/cavecrew/SKILL.md:1-50]().

The decision matrix routes tasks: small targeted fixes → `cavecrew-builder`; new features crossing 3+ files → main thread or `feature-dev:code-architect`; bug-hunt on a diff → `cavecrew-reviewer`. The rule of thumb printed in the skill: **pick cavecrew when you would want the output in 1/3 the tokens; pick vanilla when you want prose rationale** Source: [skills/cavecrew/SKILL.md:1-50](). Subagent tool results are injected verbatim into main context, so this token savings compounds across 20+ delegations in a single session.

## Distribution and Known Limitations

Skills are mirrored into the `plugins/caveman/skills/` tree by CI on merge — contributors edit only the `skills/` source of truth and note "CI will resync `plugins/caveman/skills/...`" in the PR description Source: [CONTRIBUTING.md:1-50](). Auto-discovery files at the repo root (`AGENTS.md`, `GEMINI.md`) `@`-include the four primary `SKILL.md` files so host agents that respect autodiscovery (Cursor, Windsurf, Cline, Copilot) load them passively Source: [AGENTS.md:1-10](), [GEMINI.md:1-10]().

Provider plugins copy skill files to provider-specific paths. The opencode plugin copies command files like `caveman-compress.md` to `~/.config/opencode/commands/` and registers the `caveman-shrink` MCP proxy ([src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json)) for tool-description compression. Several community-reported gaps are visible in the issue tracker and worth knowing when adopting the system: the opencode plugin's `session.created` and `tui.prompt.append` hook keys are not triggered by opencode's actual API (issues #418, #482), the opencode installer fails with `ENOENT` on `caveman-compress.md` until the missing file is shipped (issues #367, #464), the `caveman-shrink` MCP proxy is registered with no upstream command and fails to start on every load (issue #474), and the PowerShell 7 installer fails on `Cannot overwrite variable Args` (issue #366). v1.9.0 added tag-pinned installs and SHA-256 verification of hook files against `src/hooks/checksums.sha256` to harden `curl|bash` flows Source: [CLAUDE.md:1-50]().

## See Also

- [Installation & Provider Matrix](#) — agent-specific install commands and provider support table
- [Compression Rules Reference](#) — full remove/keep list with intensity-level examples
- [Cavecrew Subagent Reference](#) — detailed dispatch matrix and output contracts
- [Security & Hook Integrity](#) — tag pinning and SHA-256 verification in v1.9.0

---

<a id='page-3'></a>

## Hooks, Plugins, and MCP Integration

### Related Pages

Related topics: [Skills and Behavior System](#page-2), [Installer and Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)
- [src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json)
- [src/mcp-servers/caveman-shrink/compress.js](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js)
- [src/plugins/opencode/plugin.js](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)
- [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md)
- [src/plugins/opencode/commands/caveman-commit.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-commit.md)
- [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md)
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md)
- [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md)
- [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md)
- [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)
</details>

# Hooks, Plugins, and MCP Integration

## 1. Purpose and Scope

The caveman project ships three distinct integration layers so that the same terse-prose rules can reach as many coding agents as possible without forking the core prompt:

- **Claude Code hooks** — small Node/PowerShell scripts that fire on session lifecycle events and inject the ruleset.
- **Per-agent plugins** — directory trees copied into each agent's config root (opencode, Codex, Gemini CLI, Cursor, Windsurf, Cline, Copilot, OpenClaw, etc.).
- **An MCP server** — `caveman-shrink`, a Model Context Protocol proxy that compresses tool descriptions on the fly.

The shared payload is the ruleset itself, kept at [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md). The file is short by design — a model reads it once at session start, then drops articles, filler words, pleasantries, and hedging while keeping every technical term, code block, and symbol intact. Boundaries are explicit: code, commits, and PRs are written in normal prose, never in caveman style. Source: [src/rules/caveman-activate.md:1-12]().

## 2. Architecture Overview

```mermaid
flowchart LR
    A[caveman repo] --> B[src/rules/caveman-activate.md]
    A --> C[src/hooks/*]
    A --> D[src/plugins/opencode/]
    A --> E[plugins/caveman/]
    A --> F[src/mcp-servers/caveman-shrink/]
    B -- SessionStart hook --> G[Claude Code]
    D -- session.created hook --> H[opencode]
    E -- copy to ~/.config/<agent>/ --> I[Codex, Gemini, Cursor, ...]
    F -- claude mcp add --> J[MCP clients]
    C --> K[src/hooks/checksums.sha256<br/>v1.9.0 pin + SHA-256]
```

### Distribution by Agent

| Agent | Mechanism | Auto-activates? |
|-------|-----------|----------------|
| Claude Code | Plugin (hooks + skills) or standalone hooks from `src/hooks/` | Yes — `SessionStart` injects rules |
| opencode | Native plugin in `src/plugins/opencode/` copied into `~/.config/opencode/plugins/caveman/` | Yes — see §4 below for known API issues |
| Codex, Gemini, Cursor, others | Files under `plugins/caveman/` mirrored into the agent's config root | Yes on most platforms |
| OpenClaw | Workspace skill at `~/.openclaw/workspace/skills/caveman/SKILL.md` with `always: true` | Yes — bootstrap block in `SOUL.md` |
| Any MCP client | `claude mcp add caveman-shrink -- npx -y caveman-shrink` | At session start |

Source: [CLAUDE.md:11-23]().

## 3. Hooks Layer

Hooks are the load-bearing mechanism for Claude Code. The contributing guide is explicit: "Hooks must silent-fail on filesystem errors. A `try/catch` that swallows the error is correct here. A hook that throws blocks Claude Code session start — that's user-facing breakage." Source: [CONTRIBUTING.md:24-26]().

The ruleset injected by the `SessionStart` hook is intentionally compact. It encodes:

- A drop list — articles (`a`, `an`, `the`), filler (`just`, `really`, `basically`), pleasantries, hedging.
- A pattern — `[thing] [action] [reason]. [next step].`
- A switch grammar — `/caveman lite|full|ultra|wenyan` toggles intensity.
- An Auto-Clarity rule — caveman falls back to normal prose for security warnings, irreversible actions, and confused users, then resumes.

Source: [src/rules/caveman-activate.md:1-12]().

As of v1.9.0, detached and `curl|bash` installs no longer fetch hooks from the moving `main` branch. They download from the immutable `v1.9.0` tag and verify each hook against `src/hooks/checksums.sha256` (SHA-256) before execution; a mismatch aborts the install. Source: [release notes for v1.9.0](https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.0).

## 4. OpenCode Plugin Integration

The opencode plugin is a thin native shim. The installer copies files from `src/plugins/opencode/commands/` into `~/.config/opencode/commands/`. Two commands are shipped:

- `caveman-compress.md` — invokes the compress skill against a given filepath, refuses source/config extensions, and never overwrites a `*.original.md` backup. Source: [src/plugins/opencode/commands/caveman-compress.md:1-12]().
- `caveman-commit.md` — produces a Conventional Commits message with a ≤50-char subject, body only for non-obvious "why". Source: [src/plugins/opencode/commands/caveman-commit.md:1-6]().

### Known Failure Modes

Several community-reported issues cluster around this plugin and are worth understanding before debugging:

- **Missing files in the published package.** The installer references `caveman-compress.md` in the commands list, but the file can be absent from the npm tarball, causing `ENOENT` at copy time. Sources: [#367](https://github.com/JuliusBrussee/caveman/issues/367), [#426](https://github.com/JuliusBrussee/caveman/issues/426), [#464](https://github.com/JuliusBrussee/caveman/issues/464).
- **Hook names that the opencode API does not implement.** `src/plugins/opencode/plugin.js` registers `session.created` and `tui.prompt.append` as triggerable hooks, but opencode's plugin API does not actually fire either of them. The plugin appears to install successfully yet rules never inject, so the first prompt works and every subsequent one reverts to verbose. Source: [#418](https://github.com/JuliusBrussee/caveman/issues/418).
- **Session stickiness.** Even when the hook does fire, the activation does not persist across prompts in some `omp` configurations. Source: [#16](https://github.com/JuliusBrussee/caveman/issues/16).

## 5. MCP Server: caveman-shrink

`caveman-shrink` is the project's MCP-side piece. Its package manifest declares it as an MCP proxy that compresses prose fields (tool descriptions, etc.) using the same rules as the in-prompt compressor, with the goal of "Same accuracy, fewer context tokens." Source: [src/mcp-servers/caveman-shrink/package.json:1-3]().

The compressor itself re-implements the Python rules in pure Node so the proxy stays single-runtime. It exports `compress(text, opts?) → { compressed, before, after }`. Source: [src/mcp-servers/caveman-shrink/compress.js:1-7]().

### Compression Boundaries

| Region | Treatment |
|--------|-----------|
| Fenced code blocks (``` ... ```) | Never touched |
| Inline code (`...`) | Never touched |
| URLs (`https?://...`) | Never touched |
| Filesystem paths (anything with `/` or `\`) | Never touched |
| Code-looking tokens (trailing parens, semicolons, JSON-like braces) | Never touched |
| CamelCase / snake_case / dotted.path identifiers | Never touched |
| Everything else | Articles, filler (`just`, `really`, `basically`, ...), pleasantries (`please`, `kindly`, ...), hedging (`perhaps`, `maybe`, ...), and leading "I'll / I will / you can / we will / let me" are stripped; whitespace runs are collapsed. |

Source: [src/mcp-servers/caveman-shrink/compress.js:9-22]()

### Known Failure Mode

The default installer registers the server with no upstream command — `claude mcp add caveman-shrink -- npx -y caveman-shrink` — so the proxy fails to start on every session. Mitigation is to wrap the proxy around an actual upstream rather than register the bare binary. Source: [#474](https://github.com/JuliusBrussee/caveman/issues/474).

## 6. Cavecrew Subagent Layer

`cavecrew` is the fourth integration path: a family of cavecrew-prefixed subagents (`investigator`, `builder`, `reviewer`) whose output contracts are designed for main-context re-injection. The compression win comes from the fact that subagent tool results land in main context verbatim, so a 2k-token prose report is a 2k-token budget hit every time, while a `cavecrew-investigator` report — `path:line — \`symbol\` — short note` plus `totals:` — costs roughly a third. Source: [skills/cavecrew/SKILL.md:1-19]().

Each subagent's frontmatter currently pins a default model (e.g. `cavecrew-reviewer` → `haiku`). Haiku is the right cheap default but is sometimes too weak as a real pre-merge review gate, so per-agent model overrides are an open request. Source: [#521](https://github.com/JuliusBrussee/caveman/issues/521).

## 7. Common Pitfalls and Mitigations

| Symptom | Likely cause | Mitigation |
|---------|--------------|------------|
| `/caveman` not visible after install | Agent-specific install path not triggered (e.g. IBM Bob) | Use `npx skills add JuliusBrussee/caveman -a <agent>` and verify the agent's skills directory directly |
| Install aborts on PowerShell 7 | `Args` variable is optimized in PS7+; installer tries to overwrite it | Source: [#366](https://github.com/JuliusBrussee/caveman/issues/366) |
| Gemini CLI extension fails to load | Invalid agent frontmatter or TOML against Gemini's extension schema | Source: [#325](https://github.com/JuliusBrussee/caveman/issues/325) |
| Caveman works once, then reverts | opencode plugin hook names are wrong | Source: [#418](https://github.com/JuliusBrussee/caveman/issues/418) |
| MCP server fails on every load | `caveman-shrink` registered with no upstream | Source: [#474](https://github.com/JuliusBrussee/caveman/issues/474) |
| Security scanner flags "Caution" | Hook code performs outbound network calls during install | Source: [#528](https://github.com/JuliusBrussee/caveman/issues/528) — v1.9.0's pin + SHA-256 verification is the project's answer to this |

## See Also

- [Caveman Compress Skill](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) — the file-compression rule set that `caveman-compress.md` command delegates to.
- [Cavecrew Subagent Delegation](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md) — token-aware subagent output contracts.
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md) — hook silent-fail rule, settings.json JSONC tolerance, and frontmatter validation requirements.

---

<a id='page-4'></a>

## Installer and Troubleshooting

### Related Pages

Related topics: [Overview and Installation Guide](#page-1), [Hooks, Plugins, and MCP Integration](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [bin/install.js](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)
- [bin/lib/openclaw.js](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/openclaw.js)
- [bin/lib/opencode-agent.js](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/opencode-agent.js)
- [src/hooks/install.sh](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/install.sh)
- [src/hooks/install.ps1](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/install.ps1)
- [src/hooks/uninstall.sh](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/uninstall.sh)
- [src/hooks/checksums.sha256](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/checksums.sha256)
- [src/plugins/opencode/plugin.js](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)
- [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md)
- [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)
- [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md)
- [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md)
</details>

# Installer and Troubleshooting

## Overview

The caveman installer is the entry point for every supported coding agent. It ships three layers: a Node.js orchestrator (`bin/install.js`), per-agent adapter libraries in `bin/lib/`, and per-platform shell hook scripts under `src/hooks/`. Together they copy skills, commands, agents, and SessionStart hooks into the target agent's config directory and verify that the resulting wiring is consistent.

The installer is **pinned and integrity-checked** as of v1.9.0. Per the release notes, `curl|bash` and detached installs no longer fetch hook files from the moving `main` branch — they download from the immutable `v1.9.0` tag and verify every hook against `src/hooks/checksums.sha256` (SHA-256) before execution. A mismatch aborts the install.

Source: [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md); [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md).

## Install Paths per Agent

The installer branches by target agent. Each branch writes the same set of skills (`caveman`, `cavecrew`, `caveman-commit`, `caveman-compress`, `caveman-review`) plus an activation rule file, but the destination paths and mechanism differ. The high-level distribution matrix:

| Agent | Mechanism | Destination | Auto-activates? |
|-------|-----------|-------------|----------------|
| Claude Code | Plugin (hooks + skills) or standalone hooks | `~/.claude/` | Yes — SessionStart hook injects rules |
| Codex | Plugin in `plugins/caveman/` + `.codex/hooks.json`, `.codex/config.toml` | repo + `~/.codex/` | Yes on macOS/Linux |
| Gemini CLI | Extension with `GEMINI.md` context file | `~/.gemini/extensions/` | Yes — context file loads every session |
| opencode | Native plugin copied to `~/.config/opencode/plugins/caveman/` + `AGENTS.md` ruleset + skills/agents/commands dirs | `~/.config/opencode/` | Yes — `session.created` writes flag |
| OpenClaw | Workspace skill at `~/.openclaw/workspace/skills/caveman/SKILL.md` (frontmatter merged with `version` + `always: true`) plus a marker-fenced bootstrap block in `~/.openclaw/workspace/SOUL.md` | `~/.openclaw/workspace/` | Yes — writes go through `bin/lib/openclaw.js` |

Source: [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md); [bin/lib/openclaw.js](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/openclaw.js); [bin/lib/opencode-agent.js](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/opencode-agent.js).

## Installer Flow

```mermaid
flowchart TD
  A[User invokes npx / curl-pipe / npm] --> B{Target agent?}
  B -->|claude| C[Write hooks + skills to ~/.claude/]
  B -->|codex| D[Write plugin + .codex/hooks.json]
  B -->|gemini| E[Install extension w/ GEMINI.md]
  B -->|opencode| F[Copy plugin + AGENTS.md + commands]
  B -->|openclaw| G[Write workspace SKILL.md + SOUL.md block]
  C --> H[Fetch hook files from v1.9.0 tag]
  D --> H
  E --> H
  F --> H
  G --> H
  H --> I[Verify vs src/hooks/checksums.sha256]
  I -->|match| J[Install complete, SessionStart fires]
  I -->|mismatch| K[Abort install]
```

The PowerShell path mirrors the POSIX path through `src/hooks/install.ps1` and `src/hooks/install.sh`. The `uninstall.sh` script reverses all writes deterministically.

Source: [src/hooks/install.sh](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/install.sh); [src/hooks/install.ps1](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/install.ps1); [src/hooks/uninstall.sh](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/uninstall.sh).

## Known Failure Modes and Fixes

The community has surfaced a handful of recurring installer failures. Each maps to a specific source path.

### opencode ENOENT (`caveman-compress.md` missing)

`bin/install.js` declares an `OPENCODE_COMMAND_FILES` array but, prior to v1.9.0, referenced files that were not actually shipped (`caveman-compress.md`). Install fails with:

```
ENOENT: no such file or directory, copyfile '.../src/plugins/opencode/commands/caveman-compress.md' -> '.../commands/caveman-compress.md'
```

Fix: ensure the file exists in the package (`src/plugins/opencode/commands/caveman-compress.md`), or remove it from `OPENCODE_COMMAND_FILES` so the installer skips it gracefully. References: issues #426, #464, #482, #367.

### opencode plugin hooks never fire

`src/plugins/opencode/plugin.js` registered `session.created` and `tui.prompt.append` as named hook keys, but opencode's plugin API does not support those names. Result: the plugin loads, but caveman never auto-activates in a session. Reference: issue #418. The activation rules are then delivered via the `AGENTS.md` ruleset instead.

### PowerShell 7 `Cannot overwrite variable Args`

On PowerShell 7+, the `irm ... | iex` pipeline fails with `Invoke-Expression: Cannot overwrite variable Args because the variable has been optimized`. Reference: issue #366. Workarounds: pin to v1.9.0 (the script now ships a manifest and integrity check), or run the installer from a local checkout rather than the one-liner.

### caveman-shrink MCP starts with no upstream

Default install ran `claude mcp add caveman-shrink -- npx -y caveman-shrink`, which registers the proxy with no real upstream command and fails on every session load. Reference: issue #474. Verify the proxy entry in `~/.claude.json` points at a valid `npx` target before each session.

### Gemini CLI extension fails to validate

`gemini extensions install` rejects caveman's agents and `/caveman-init` command when the frontmatter or TOML schema is invalid. Reference: issue #325. Re-run after pulling a tag that conforms to Gemini's extension schema.

### IBM Bob activation

`npx skills add JuliusBrussee/caveman -a bob` reports success, but `/caveman` does not appear in Bob's command list. Reference: issue #523. Bob's skill loader uses a different frontmatter contract than Claude Code; consult Bob's plugin docs for the correct activation flag.

### Security-scan cautions

Some scanners flag caveman's hooks as "Caution" for high-risk exfiltration and medium-risk path traversal. Reference: issue #528. The v1.9.0 pinned-tag install plus SHA-256 checksums (in `src/hooks/checksums.sha256`) are the project's primary mitigation — they prove the exact bytes that will be written.

### Cavecrew subagent model pinning

`cavecrew-reviewer` and other cavecrew agents hardcode `model: haiku` in their frontmatter, which is too weak as a real pre-merge gate. Reference: issue #521. Override per-agent via the host agent's model selection once the upstream supports it.

## Verification and Recovery

After any install, verify:

1. The SessionStart hook fires — start a new Claude Code session and check that responses are terse on the first turn. Source: [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md).
2. Skills list — `/caveman`, `/caveman-commit`, `/caveman-compress` should all appear.
3. Checksums — for `curl|bash` and `irm|iex` paths, the installer aborts on mismatch, so a clean exit implies integrity.

For rollback, `src/hooks/uninstall.sh` removes all written files. For partial failures, the contributing guide recommends reading and writing `settings.json` through `bin/lib/settings.js` (JSONC-tolerant) rather than direct `JSON.parse`, since a single `// comment` would otherwise crash the parse. Source: [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md).

## See Also

- [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md) — repo overview and intensity levels
- [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) — per-agent distribution matrix
- [INSTALL.md](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) — full install guide
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md) — `settings.json` invariants and CI sync rules
- v1.9.0 release notes — pinned installs and SHA-256 checksums (#261, #262)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: JuliusBrussee/caveman

Summary: Found 34 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/482

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/464

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal)
- User impact: Developers may expose sensitive permissions or credentials: Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal)
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/528

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/523

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/457

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Can't find or activate /caveman in IBM Bob
- User impact: Developers may fail before the first successful local run: Can't find or activate /caveman in IBM Bob
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/523

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Portuguese (PT-BR) adaptation: Troglodita
- User impact: Developers may fail before the first successful local run: Portuguese (PT-BR) adaptation: Troglodita
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/457

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: ask about project
- User impact: Developers may fail before the first successful local run: ask about project
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/522

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: caveman does not work when installing for opencode
- User impact: Developers may fail before the first successful local run: caveman does not work when installing for opencode
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/482

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: caveman-shrink MCP registered with no upstream → fails on every load
- User impact: Developers may fail before the first successful local run: caveman-shrink MCP registered with no upstream → fails on every load
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/474

## 11. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate)
- User impact: Developers may fail before the first successful local run: feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate)
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/521

## 12. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md
- User impact: Developers may fail before the first successful local run: npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/464

## 13. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: opencode install fails with ENOENT for missing caveman-compress.md
- User impact: Developers may fail before the first successful local run: opencode install fails with ENOENT for missing caveman-compress.md
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/426

## 14. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink
- User impact: Upgrade or migration may change expected behavior: v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink
- Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.7.0

## 15. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.8.0 — Lobster grunt. Opencode grunt. Brain still big.
- User impact: Upgrade or migration may change expected behavior: v1.8.0 — Lobster grunt. Opencode grunt. Brain still big.
- Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.0

## 16. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.8.1 — Hotfix: curl|bash one-liner
- User impact: Upgrade or migration may change expected behavior: v1.8.1 — Hotfix: curl|bash one-liner
- Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.1

## 17. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.8.2 — installer bug fixes
- User impact: Upgrade or migration may change expected behavior: v1.8.2 — installer bug fixes
- Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.2

## 18. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.9.0 — Rock pinned. Rock verified. opencode rock work now.
- User impact: Upgrade or migration may change expected behavior: v1.9.0 — Rock pinned. Rock verified. opencode rock work now.
- Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.0

## 19. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/474

## 20. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/521

## 21. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/426

## 22. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman

## 23. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API
- User impact: Developers may misconfigure credentials, environment, or host setup: bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/418

## 24. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/418

## 25. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman

## 26. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude-sonnet-4-6
- User impact: Developers may hit a documented source-backed failure mode: benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude-sonnet-4-6
- Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/519

## 27. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/519

## 28. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman

## 29. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman

## 30. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman

## 31. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/528

## 32. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/522

## 33. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman

## 34. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman

<!-- canonical_name: JuliusBrussee/caveman; human_manual_source: deepwiki_human_wiki -->