Related Pages

Related topics: Skills and Behavior System, Installer and Troubleshooting

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

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:

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. 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, #426, #464, #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, #16).
3. PowerShell 7 installer fails — irm | iex errors with Cannot overwrite variable Args because the variable has been optimized (#366).
4. Gemini CLI extension fails to load — invalid agent frontmatter and invalid TOML surface three loader errors against the Gemini extension schema (#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).

A security note from issue #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 — agent-by-agent distribution matrix and code style invariants
• README.md — public landing page and benchmark headlines
• CONTRIBUTING.md — PR conventions and package.json files rules
• src/mcp-servers/caveman-shrink/ — MCP proxy implementation
• skills/caveman-compress/ — file compressor source

Related Pages

Related topics: Overview and Installation Guide, Hooks, Plugins, and MCP Integration

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 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 and surfaced to users in 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) 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

Related Pages

Related topics: Skills and Behavior System, Installer and Troubleshooting

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. 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

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

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.

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, #426, #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.
• Session stickiness. Even when the hook does fire, the activation does not persist across prompts in some omp configurations. Source: #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

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.

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.

7. Common Pitfalls and Mitigations

See Also

• Caveman Compress Skill — the file-compression rule set that caveman-compress.md command delegates to.
• Cavecrew Subagent Delegation — token-aware subagent output contracts.
• CONTRIBUTING.md — hook silent-fail rule, settings.json JSONC tolerance, and frontmatter validation requirements.

Related Pages

Related topics: Overview and Installation Guide, Hooks, Plugins, and MCP Integration

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; 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:

Source: CLAUDE.md; bin/lib/openclaw.js; bin/lib/opencode-agent.js.

Installer Flow

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; src/hooks/install.ps1; 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.
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.

See Also

• README.md — repo overview and intensity levels
• CLAUDE.md — per-agent distribution matrix
• INSTALL.md — full install guide
• CONTRIBUTING.md — settings.json invariants and CI sync rules
• v1.9.0 release notes — pinned installs and SHA-256 checksums (#261, #262)

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/482

2. Installation risk: Installation risk requires verification

• Severity: high
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/464

3. Security or permission risk: Security or permission risk requires verification

• Severity: high
• 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)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal). Context: Observed during installation or first-run setup.
• 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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/523

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/457

6. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Can't find or activate /caveman in IBM Bob. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/523

7. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Portuguese (PT-BR) adaptation: Troglodita. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/457

8. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: ask about project. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/522

9. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: caveman does not work when installing for opencode. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/482

10. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: caveman-shrink MCP registered with no upstream → fails on every load. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/474

11. Installation risk: Installation risk requires verification

• Severity: medium
• 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)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate). Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/521

12. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/464

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using caveman with real data or production workflows.

• Can't find or activate /caveman in IBM Bob - github / github_issue
• Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk - github / github_issue
• Portuguese (PT-BR) adaptation: Troglodita - github / github_issue
• caveman does not work when installing for opencode - github / github_issue
• npx install for opencode incomplete — no such file or directory src\plug - github / github_issue
• ask about project - github / github_issue
• feat: per-agent model override for cavecrew subagents (reviewer hardcode - github / github_issue
• benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired ( - github / github_issue
• opencode install fails with ENOENT for missing caveman-compress.md - github / github_issue
• bug(opencode): plugin hooks session.created and tui.prompt.append never - github / github_issue
• caveman-shrink MCP registered with no upstream → fails on every load - github / github_issue
• v1.9.0 — Rock pinned. Rock verified. opencode rock work now. - github / github_release