pi-caveman

Native Pi caveman communication mode: fewer output tokens, same technical accuracy.

Highlights

• Each mode has a clear personality the model actually picks up and holds across multiple turns.
• Lite gives you tight professional sentences instead of telegraph-style fragments.
• Replies stay as flowing chat — no markdown headers turning every answer into a doc page.
• Plain-English safety mode triggers only for genuinely destructive commands, not whenever you say "I'm confused" or ask about security.
• No leftover marker lines or odd Caveman ask: prefixes showing up in your answers.
• Commit messages, PR descriptions, reviews, and anything you're sending to others stay normal English.
• Warns you when your Claude-bridge setup would silently drop caveman before it reaches the model.
• Per-session sidecar state preserves session overrides across pi -r, including slash-command changes made before the next model turn.
• Tested across multiple providers and real back-and-forth conversations, not just one-shot prompts.

Install

Via npm:

pi install npm:@vanillagreen/pi-caveman

Via vstack:

cargo install --git https://github.com/vanillagreencom/vstack.git vstack
vstack add vanillagreencom/vstack --pi-extension pi-caveman --harness pi -y

Restart Pi after installation.

Commands

| Command | Action | | --- | --- | | /caveman | Toggle the current session between off and the last active mode. | | /caveman:lite\|full\|ultra\|micro | Set a session override mode. | | /caveman:toggle | Toggle the session override between off and the last active mode. | | /caveman off | Disable caveman mode for the current session. | | /caveman status | Show current mode and whether it comes from settings or a session override. | | /caveman debug | Show resolved mode, settings paths, legacy-key conflicts, and the rendered prompt block. |

Arguments support autocomplete.

Modes

| Mode | Style | | --- | --- | | lite | Professional full sentences, but no filler or hedging. | | full | Classic terse caveman; fragments are OK. | | ultra | Maximum English compression with abbreviations and arrows. | | micro | Shortest prompt injection for token-sensitive sessions. |

Behavior

• Mode is stored in your Pi settings and applied at the start of every model turn. The extension steers style; it doesn't rewrite the model's output.
• /caveman slash commands set a per-session override. Active non-off defaults are snapshotted into new sessions, so resuming with pi -r keeps the mode that session started with even if your global default changes later. Changing the default in the extension manager replaces any active override in the current session.
• When you type a destructive command (force-push, hard reset, drop table, rm -rf, etc.), caveman steps aside for that one reply and the model writes plain English. Caveman resumes automatically on the next turn.
• Caveman applies to chat replies only. Commit messages, PR descriptions, formal reviews, and anything you send to other systems (issue bodies, PR comments, chat, email) stay normal English.
• pi-qol uses this extension to show a Caveman badge in the status line and bind a configurable shortcut to cycle modes.

Settings

All settings are toggled in the extension manager (or written directly to Pi/vstack settings.json).

Project settings in .pi/settings.json apply only after Pi marks the workspace trusted; before trust, vstack Pi extensions read user/global settings only.

| Setting | Default | What it does | | --- | --- | --- | | mode | off | Default caveman mode for new sessions. | | showStatusBadge | true | Show the caveman badge in the status line while active. | | sessionOverrideAllowed | true | Allow /caveman commands to override the default within a session. | | autoClarityEscape | true | Switch to plain English for one reply when the user prompt names a destructive operation. | | resumeAfterClarityEscape | true | Resume caveman automatically on the next turn after a safety override. | | boundaryNormalForCode | true | Keep code blocks and quoted errors normal English. | | boundaryNormalForCommits | true | Keep commit messages and PR descriptions normal English. | | boundaryNormalForReviews | true | Keep formal reviews normal English. | | boundaryNormalForExternalWrites | true | Keep issue bodies, PR comments, code review messages, and chat/email normal English. | | customPromptSuffix | "" | Extra project-specific guidance appended to the caveman directive. |

Claude-bridge users

pi-caveman injects its directive into Pi's systemPrompt. When you use claude-bridge as your provider, claude-bridge builds its own systemPrompt from Claude Code's preset and only forwards pi-side hooks that you explicitly enable. The caveman directive is one of those hooks.

• Set @vanillagreen/pi-claude-bridge → includeCavemanHook: true in the extension manager. The default is off.
• If caveman is active and the bridge is installed with this flag off, pi-caveman warns once at session start. Run /caveman debug to confirm the resolved bridge setting.
• Non-bridge providers (native Pi providers) receive the caveman block as part of Pi's regular systemPrompt and do not need this flag.