AI Coding Agents Compatible with Caveman: Complete Setup Guide

Caveman integrates with 30+ AI coding agents through automatic session hooks or static rule files, supporting Claude Code, Gemini CLI, opencode, OpenClaw, Hermes, Cursor, Windsurf, and GitHub Copilot.

Caveman is a compression skill developed in the JuliusBrussee/caveman repository that attaches to AI coding agents to reduce verbose output while preserving code, paths, and error messages byte-for-byte. The installer detects and configures over 30 agents out-of-the-box, making it one of the most widely compatible developer productivity tools for AI-assisted programming workflows.

Auto-Activating AI Coding Agents

Certain AI coding agents support plugin architectures or extension systems that allow Caveman to activate automatically when a session starts. These agents require no manual intervention after initial installation.

Claude Code

Claude Code offers the most seamless integration through its plugin marketplace and hook system. The installer writes JavaScript hook files into ~/.claude/ that fire on session start.

Install via the marketplace:

claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

Once installed, Caveman activates automatically when you start a Claude Code session. The hooks located in src/hooks/caveman-activate.js, caveman-mode-tracker.js, and caveman-stats.js handle activation and report token-saving statistics to the status line.

Gemini CLI

Gemini CLI supports Caveman through its extensions system with automatic activation enabled.

Installation command:

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

Opencode

Opencode receives full plugin treatment including the cavecrew sub-agents. The installer adds a plugin directory under ~/.config/opencode/plugins/caveman/ and injects Caveman agents into ~/.config/opencode/agents/AGENTS.md.

Install using the Node installer:

node bin/install.js --only opencode

Or via npx:

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

OpenClaw and Hermes Agent

OpenClaw and Hermes Agent both support automatic activation through workspace skills.

For OpenClaw:

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

This adds a workspace skill and a marker block to SOUL.md. For Hermes Agent, use the same npx pattern with --only hermes.

Manual Activation and Static Rule Agents

Many popular AI coding agents lack hook systems but support static rule files. For these agents, Caveman drops a caveman-activate.md file into the agent's per-repo configuration directory, making compression available via the /caveman slash command.

Cursor, Windsurf, and Cline

Cursor, Windsurf, and Cline require manual activation each session unless you use the --with-init flag to drop a permanent rule file.

Install for Cursor with permanent rules:

npx skills add JuliusBrussee/caveman -a cursor --with-init

This creates ./.cursor/rules/caveman.mdc. Without --with-init, you must type /caveman each session:

npx skills add JuliusBrussee/caveman -a cursor

Windsurf and Cline follow identical patterns using -a windsurf or -a cline respectively.

GitHub Copilot

GitHub Copilot operates in "soft probe" mode. Use the --with-init flag to install the static rule file:

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

Continue, Kilo Code, Roo Code, and Augment Code

These community agents install via the generic profile system but lack automatic activation:

npx skills add JuliusBrussee/caveman -a <profile>

Replace <profile> with continue, kilo-code, roo-code, or augment-code. The full list of supported profiles is defined in the PROVIDERS array within bin/install.js.

How Caveman Architecture Supports Multiple Agents

The bin/install.js installer serves as the central orchestrator that detects which agents are present on the host, then runs the appropriate installation command for each. It reads the agent matrix, decides which files to copy, and writes a .caveman-active flag file that the runtime checks to determine compression levels.

Skill Files

The core Caveman logic lives in skills/caveman/. When an agent loads this skill, it replaces verbose output fragments with terse "caveman-speak" while preserving code, paths, and error messages byte-for-byte.

Per-Agent Hook System

For agents exposing hook systems (Claude Code), the installer writes JavaScript activation hooks into the agent's config directory. These hooks turn compression mode on automatically when sessions start and track statistics via caveman-stats.js.

Static Rule Files

For agents without hooks, the installer copies src/rules/caveman-activate.md into appropriate locations (e.g., .cursor/rules/caveman.mdc). This file contains the caveman-begin / caveman-end markers and command definitions (/caveman, /caveman-commit).

Sub-Agent Integration

The repository ships with cavecrew sub-agents (agents/cavecrew-*.md). When an opencode install occurs, these markdown agents are sanitized and added to the opencode agents directory, letting the sub-agents themselves benefit from Caveman's compression.

Installation Examples by Agent

Claude Code (Automatic Activation)

The fastest installation method for Claude Code uses the install script:

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

Start a session and type:

/caveman

The agent replies in compact form, e.g., "New ref each render. Wrap in useMemo."

Cursor (Permanent Rule File)

For persistent Cursor integration without per-session activation:

node bin/install.js --only cursor --with-init

This creates .cursor/rules/caveman.mdc. Trigger compression with:

/caveman full

Opencode (With Sub-Agents)

Enable Caveman and the cavecrew reviewers:

node bin/install.js --only opencode

Invoke the review agent:

/caveman-review

Key Source Files

Path	Purpose
bin/install.js	Central installer containing the PROVIDERS array and auto-detection logic
src/rules/caveman-activate.md	Static rule defining /caveman commands for agents without hooks
src/hooks/caveman-activate.js	Session start hook for Claude Code auto-activation
src/hooks/caveman-stats.js	Token-saving statistics reporter
agents/cavecrew-reviewer.md	Example sub-agent benefiting from Caveman compression
src/plugins/opencode/commands/caveman.md	Opencode command implementation

Summary

• Caveman supports 30+ AI coding agents through the bin/install.js installer, which detects available agents via the PROVIDERS array.
• Auto-activation works with Claude Code, Gemini CLI, opencode, OpenClaw, and Hermes Agent through plugin hooks or extension systems.
• Manual activation is required for Cursor, Windsurf, Cline, and GitHub Copilot, though the --with-init flag creates permanent static rule files.
• The installer writes hook files (caveman-activate.js) for supported agents and static rules (caveman-activate.md) for others, storing a .caveman-active flag to track state.
• Opencode installations include additional benefits: the installer sanitizes and injects agents/cavecrew-*.md sub-agents into AGENTS.md.

Frequently Asked Questions

What AI coding agents work with Caveman automatically?

Claude Code, Gemini CLI, opencode, OpenClaw, and Hermes Agent support automatic activation through plugin marketplaces or extension systems. These agents install hooks that fire on session start, eliminating the need for manual /caveman commands.

How do I install Caveman for Cursor or Windsurf?

Use the installer with the --only flag targeting your specific agent, and add --with-init to create a permanent rule file. For example: node bin/install.js --only cursor --with-init creates .cursor/rules/caveman.mdc. Without --with-init, you must manually trigger /caveman each session using npx skills add JuliusBrussee/caveman -a cursor.

What is the difference between hook-based and rule-based installation?

Hook-based installations (Claude Code, Gemini CLI) write JavaScript files into the agent's config directory that automatically activate Caveman when sessions start. Rule-based installations (Cursor, Windsurf, Cline) copy static markdown files (caveman-activate.md) into the agent's rules directory, requiring manual /caveman commands unless you use the --with-init permanent configuration flag.

Where does Caveman store its configuration files?

The installer writes hook files to agent-specific directories (e.g., ~/.claude/ for Claude Code), static rules to per-repo directories (e.g., .cursor/rules/), and a flag file named .caveman-active to track which compression level is active. The PROVIDERS array in bin/install.js defines the specific paths for each supported agent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}