How Caveman Integrates with Claude Code, Cursor, and Cline AI Coding Agents

Caveman employs a dual-architecture system using a dynamic Opencode plugin for Claude Code and static markdown rule files for Cursor and Cline to enforce compressed, filler-free communication across AI coding agents.

Caveman is a skill/plugin developed by JuliusBrussee that reduces token consumption by forcing AI assistants to adopt "caveman" style—dropping articles, hedging, and pleasantries while keeping code exact. According to the JuliusBrussee/caveman source code, the tool supports both runtime plugin integration and static configuration files to work seamlessly across different AI coding agent ecosystems.

The Dual Architecture: Dynamic Plugin vs. Static Rules

Caveman provides two complementary mechanisms to interface with AI coding agents:

1. Dynamic Opencode Plugin: Hooks into the Opencode runtime to track mode flags, intercept slash commands, and inject reinforcement lines into system prompts. This powers Claude Code and other Opencode-compatible runtimes.

2. Static Rule Files: Plain-text markdown files that agents read on startup, containing instructions to adopt caveman-speak style. This supports Cursor, Cline, Windsurf, Copilot, and approximately 30 other agents.

Both mechanisms derive from the same rule set located in src/rules/caveman-activate.md. The plugin handles state management, while static files provide the textual prompt without runtime overhead.

How the Opencode Plugin Powers Claude Code

The Opencode plugin, located at src/plugins/opencode/plugin.js, provides real-time mode management for Claude Code and similar Opencode-based agents.

Session Lifecycle and Flag Management

When Claude Code initializes a session, the plugin hooks into the session.created event via handleSessionCreated(). This function writes the default mode (e.g., ultra) to a flag file at ~/.config/opencode/.caveman-active, ensuring persistent state across long-running TUI processes.

The plugin exports three key hooks:

• event: Rewrites the flag file when session.created fires
• chat.message: Scans user input for commands like /caveman off or natural language toggles (e.g., "activate caveman")
• experimental.chat.system.transform: Appends the reinforcement line to system prompts before each LLM request

Mode Parsing and System Prompt Injection

The parseModeChange(prompt) function (lines 96-165 in src/plugins/opencode/plugin.js) detects both slash commands (/caveman, /caveman-compress) and natural language triggers, returning modes like 'ultra', 'compress', or 'off'.

When a mode change occurs, applyModeChange(mode) writes the selection to the flag file or removes it when disabling. The reinforcementLine(mode) function generates context-specific nudges (e.g., "CAVEMAN MODE ACTIVE (ultra). Drop articles/filler/pleasantries/hedging…") that the transform hook injects into every system prompt.

Static Rule Files for Cursor, Cline, and Other Agents

For agents that don't support the Opencode runtime, Caveman installs static rule files that the agents read during startup.

Installation Paths and Configuration

The npx caveman --with-init command writes agent-specific rule files to the following locations:

• Cursor: ~/.config/cursor/.caveman.md or .cursor/ folder
• Cline: ~/.config/cline/.caveman.md or .clinerules/ folder
• Windsurf: ~/.config/windsurf/.caveman.md
• Copilot: ~/.github/copilot-instructions.md

These files contain the instruction: "You are a coding assistant. Answer in caveman style: drop filler, pleasantries, and hedging; keep code, commands, and errors byte-for-byte exact; you may use fragments or short sentences."

The src/tools/caveman-init.js CLI helper handles this installation, placing src/rules/caveman-activate.md content into each agent's configuration directory.

Practical Implementation Examples

Toggling Caveman Mode in Claude Code

# Start a Claude Code session

opencode run

# Enable ultra compression mode

/caveman ultra

# Disable caveman mode

/caveman off

Behind the scenes, the plugin updates ~/.config/opencode/.caveman-active and injects the reinforcement line before subsequent LLM requests.

Installing Static Rules for Cursor

# Install caveman for Cursor specifically

npx skills add JuliusBrussee/caveman -a cline

# Or initialize for all agents including Cursor and Cline

npx caveman --with-init

After installation, Cursor automatically applies the caveman prompt from ~/.config/cursor/.caveman.md without requiring additional commands.

Programmatic Mode Switching

// In a custom script using the caveman-config helper
import { safeWriteFlag } from '~/caveman-config.cjs';
const flagPath = '/home/you/.config/opencode/.caveman-active';

// Activate compress mode
safeWriteFlag(flagPath, 'compress');

The safeWriteFlag function (from src/plugins/opencode/caveman-config.cjs) safely updates the flag file, and the Opencode plugin reads this on the next turn to adjust the reinforcement line.

Summary

• Caveman uses a dual-architecture approach: a dynamic Opencode plugin for Claude Code and static rule files for Cursor, Cline, and other agents.
• The plugin at src/plugins/opencode/plugin.js manages state via flag files in ~/.config/opencode/ and injects reinforcement lines through experimental.chat.system.transform hooks.
• Static rule files in ~/.config/[agent]/ directories provide the same behavioral modifications without runtime dependencies.
• Key functions include parseModeChange() for command parsing, applyModeChange() for flag management, and reinforcementLine() for prompt injection.
• Installation via npx caveman --with-init configures both mechanisms simultaneously for cross-agent compatibility.

Frequently Asked Questions

How does Caveman detect mode changes in Claude Code?

The parseModeChange() function in src/plugins/opencode/plugin.js scans user input for slash commands like /caveman ultra or natural language phrases such as "activate caveman" and "stop caveman". It returns the appropriate mode flag, which applyModeChange() then writes to ~/.config/opencode/.caveman-active.

What is the difference between the Opencode plugin and static rule files?

The Opencode plugin provides dynamic state management, allowing users to toggle caveman mode mid-session via commands, while static rule files are read once at agent startup and provide consistent behavior without runtime overhead. Claude Code uses the plugin for interactivity, while Cursor and Cline use static files for simplicity.

Where does Caveman store its configuration files?

The Opencode plugin stores active mode flags in ~/.config/opencode/.caveman-active. Static rule files are placed in agent-specific directories: ~/.config/cursor/.caveman.md for Cursor, ~/.config/cline/.caveman.md for Cline, and ~/.config/windsurf/.caveman.md for Windsurf. The caveman-config.cjs helper provides safeWriteFlag and readFlag utilities for programmatic access.

Can I use Caveman with agents not explicitly listed?

Yes. Caveman supports any agent compatible with the Opencode runtime via the plugin, and any agent that reads instruction files from configuration directories via the static rules. The src/rules/caveman-activate.md file can be manually copied to any agent's rules directory, and the INSTALL.md documentation indicates support for 30+ agents through the skills registry.

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