How to Use the `/caveman` Command with Different Levels in JuliusBrussee/caveman

The /caveman command accepts optional level arguments—lite, full, ultra, wenyan, wenyan-lite, and wenyan-ultra—which are parsed by the mode-tracker hook in src/hooks/caveman-mode-tracker.js to set the active Caveman mode, or falls back to the default if no argument is provided.

The Caveman system modifies how Claude generates responses by enforcing specific linguistic constraints, from minimal article removal to classical Chinese syntax. To use the caveman command with different levels, you interact with a persistent flag system that tracks your preferred brevity or style setting across conversation turns. This article explains how the command parser resolves level arguments and how to configure default behaviors according to the JuliusBrussee/caveman source code.

Understanding the /caveman Command Syntax

The mode-tracker hook processes every user prompt to detect mode changes. When you type /caveman, the hook executes a multi-step resolution process defined in src/hooks/caveman-mode-tracker.js.

Command Parsing Logic

At lines 100–135, the hook checks if the prompt starts with /caveman. If detected, it splits the string into the base command and an optional argument:

// Conceptual flow from caveman-mode-tracker.js (lines 100-135)
if (prompt.startsWith('/caveman')) {
  const [command, arg] = prompt.split(/\s+/, 2);
  // arg is undefined if no level provided
}

The argument is then validated against the VALID_MODES array exported from src/hooks/caveman-config.js (lines 22–26).

Valid Mode Levels

According to the configuration file, the following levels are selectable via /caveman <level>:

• lite – Minimal linguistic compression
• full – Aggressive article removal and terse responses
• ultra – Maximum brevification and token optimization
• wenyan – Classical Chinese style (canonical alias)
• wenyan-lite – Abbreviated classical Chinese
• wenyan-ultra – Most compressed classical Chinese output

Note: wenyan-full is accepted as an alias but maps to wenyan. Independent skills like commit, review, and compress are not selectable as /caveman arguments; they require their own slash commands (/caveman-commit, etc.).

How the Mode is Applied

The mode application logic (lines 150–156 in caveman-mode-tracker.js) handles four distinct scenarios:

1. No argument provided – Activates the default mode via getDefaultMode()
2. Deactivation keywords (off, stop, disable) – Deletes the flag file to return Claude to normal mode
3. Valid mode argument – Writes the value to the flag file ($CLAUDE_CONFIG_DIR/.caveman-mode)
4. Unknown argument – Leaves the current flag unchanged (no error state)

Every transition, including deactivation, is logged to $CLAUDE_CONFIG_DIR/.caveman-mode-log.jsonl via recordModeChange() (lines 147–149) for statistical tracking.

Default Mode Resolution

When you invoke /caveman without arguments, getDefaultMode() resolves the active level through a hierarchical priority chain:

1. $CAVEMAN_DEFAULT_MODE environment variable
2. Repository-local configuration (.caveman/config.json or .caveman.json found by walking up from the current directory via findRepoConfigPath)
3. User-level configuration ($XDG_CONFIG_HOME/caveman/config.json or ~/.config/caveman/config.json)
4. Hard-coded fallback of 'full'

This hierarchy ensures that project-specific defaults override user preferences, while environment variables override both.

Deactivating Caveman Mode

Before checking for activation, the hook evaluates wantsOff logic (lines 34–46) to detect natural-language deactivation patterns. You can disable Caveman using:

/caveman off

Or via natural language equivalents:

stop caveman
turn off caveman
normal mode

These patterns trigger the deletion of the flag file, immediately restoring standard Claude behavior.

Opencode IDE Compatibility

When using Caveman inside the Opencode IDE, the plugin at src/plugins/opencode/plugin.js re-implements the parsing logic in a parseModeChange function. This ensures that /caveman <level> commands behave identically across CLI and IDE environments, writing to the same shared configuration via caveman-config.cjs.

Practical Code Examples

Switching to Specific Levels

Activate precise control over response style:

/caveman lite

/caveman ultra

/caveman wenyan-lite

Each command writes the corresponding valid mode to the persistent flag, influencing all subsequent Claude responses until changed or deactivated.

Using the Default Mode

To respect your configured default (whether set via environment variable or config file):

/caveman

This is equivalent to /caveman full only if no other default is configured in the resolution chain.

Natural Language Activation

The parser also recognizes intention without slash commands:

activate caveman mode
talk like caveman

Both trigger the default mode logic, identical to running /caveman without arguments.

Independent Skill Commands

Remember that dedicated skills do not change the persistent level:

/caveman-commit
/caveman-review
/caveman-compress

These invoke one-shot behaviors and do not modify the mode flag stored in caveman-config.js.

Summary

• The /caveman command accepts six valid level arguments (lite, full, ultra, wenyan, wenyan-lite, wenyan-ultra) defined in src/hooks/caveman-config.js
• Parsed in src/hooks/caveman-mode-tracker.js (lines 100–135), the command resolves to a default mode if no argument is provided, following a strict hierarchy from environment variables to hard-coded fallbacks
• Deactivation occurs via /caveman off or natural-language equivalents, handled by the wantsOff logic (lines 34–46)
• Opencode IDE users get identical behavior through src/plugins/opencode/plugin.js
• All mode changes are logged to .caveman-mode-log.jsonl for statistical analysis

Frequently Asked Questions

What happens if I type /caveman without any level argument?

The system invokes getDefaultMode() to resolve the active setting, checking first the $CAVEMAN_DEFAULT_MODE environment variable, then repository-local config files, then user-level config, and finally defaulting to 'full' if none are found.

Can I use /caveman to trigger commit messages or code reviews?

No. The independent skills (commit, review, compress) are not valid arguments for /caveman. You must use their dedicated commands (/caveman-commit, /caveman-review, /caveman-compress) which execute one-shot tasks without changing the persistent Caveman mode.

Where does Caveman store my current level setting?

The active mode is written to a flag file in $CLAUDE_CONFIG_DIR/.caveman-mode, and every transition is appended to $CLAUDE_CONFIG_DIR/.caveman-mode-log.jsonl for statistics. The VALID_MODES and resolution logic reside in src/hooks/caveman-config.js.

Why doesn't /caveman invalidmode change anything?

If the argument is not found in VALID_MODES and is not a deactivation keyword, the mode-tracker hook leaves the existing flag untouched (lines 150–156). This prevents accidental corruption of the current setting while silently ignoring unrecognized input.

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