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

> Discover how Caveman integrates with Claude Code, Cursor, and Cline AI coding agents. Learn about its dual-architecture system for efficient, filler-free communication.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js) CLI helper handles this installation, placing [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) content into each agent's configuration directory.

## Practical Implementation Examples

### Toggling Caveman Mode in Claude Code

```bash

# 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

```bash

# 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

```javascript
// 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) file can be manually copied to any agent's rules directory, and the [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) documentation indicates support for 30+ agents through the skills registry.