pi-caveman

Caveman mode for pi. Ultra-compressed communication — cuts 65% output tokens (measured), full technical accuracy.

Upstream: JuliusBrussee/caveman

Features

• Auto-activates on every pi session (default: full intensity)
• 6 intensity levels — from lite (professional but tight) to wenyan-ultra (classical Chinese extreme compression)
• Per-turn reinforcement keeps model in caveman mode even after context compression
• Natural language triggers — "talk like caveman", "be brief", "stop caveman"
• Status bar shows current mode with color-coded indicator
• Configurable via env var, repo-local, or user-global config
• Token savings stats — tracks and displays estimated savings per session

Install

npm (recommended)

pi install @izhimu/pi-caveman

From git

# Global
pi install git:github.com/izhimu/pi-caveman

# Project-local (shared with team via .pi/settings.json)
pi install git:github.com/izhimu/pi-caveman -l

From local path

pi install /path/to/pi-caveman
pi install ./relative/path/to/pi-caveman

Quick test (no install)

pi -e ./extensions/caveman.ts

Commands

Command	Effect
/caveman	Activate with default mode
/caveman lite	Lite mode — no filler, keep articles
/caveman full	Full mode — fragments OK, short synonyms
/caveman ultra	Ultra mode — one word when one word enough
/caveman wenyan	文言文 mode (classical Chinese)
/caveman off	Deactivate
/caveman-config	Show/set default mode
/caveman-off	Convenience alias for /caveman off
/caveman-status	Show current mode and config

Natural-language triggers also work: "talk like caveman", "stop caveman", "normal mode".

Intensity Levels

Level	Description
lite	No filler/hedging. Keep articles + full sentences. Professional but tight
full	Drop articles, fragments OK, short synonyms. Classic caveman
ultra	Strip conjunctions. One word when one word enough
wenyan-lite	Semi-classical Chinese. Drop filler but keep grammar structure
wenyan-full	Maximum classical Chinese terseness. 80-90% character reduction
wenyan-ultra	Extreme abbreviation with classical Chinese feel

Examples

Q: "Why React component re-render?"

• lite: "Your component re-renders because you create a new object reference each render. Wrap it in useMemo."
• full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."
• ultra: "Inline obj prop, new ref, re-render. useMemo."
• wenyan-full: "每繪新生對象參照，故重繪；以 useMemo 包之則免。"

Configuration

Quickest way: /caveman-config ultra — writes user config, shows all available modes.

Default mode resolution order:

1. CAVEMAN_DEFAULT_MODE environment variable
2. Repo-local: .caveman/config.json or .caveman.json (walks up to root)
3. User: ~/.config/caveman/config.json (or %APPDATA%\caveman\config.json on Windows)
4. full (fallback)

Manual config:

{
  "defaultMode": "ultra"
}

How It Works

pi loads extensions from ~/.pi/agent/extensions/ and .pi/extensions/. This extension hooks into four lifecycle events:

1. session_start — writes mode flag, notifies user
2. before_agent_start — injects reinforcement line per turn
3. input — intercepts /caveman commands and natural-language triggers
4. turn_end — updates status bar with savings stats

The SKILL.md in skills/caveman/ is auto-discovered by pi's skill system and loaded into system context.

Project Structure

pi-caveman/
├── extensions/
│   └── caveman.ts        # pi ExtensionAPI integration
├── skills/
│   └── caveman/
│       └── SKILL.md      # Caveman behavior rules
├── package.json          # pi package manifest
├── tsconfig.json
├── LICENSE
└── README.md

Flag File

Mode state persisted at ~/.pi/.caveman-active. Mode transitions logged to ~/.pi/.caveman-mode-log.jsonl.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

License

MIT © izhimu