How to Use Wenyan Mode (Classical Chinese Compression) in Caveman

Enable Wenyan mode by typing /caveman wenyan-full, /caveman wenyan-lite, or /caveman wenyan-ultra in chat to compress replies into classical Chinese (文言文) and reduce token usage by up to 90%.

Caveman is a token-saving compression layer designed for chat interfaces that dynamically rewrites response styles. The Wenyan mode feature translates technical explanations into classical Chinese registers, achieving significant token reduction while maintaining semantic precision. This guide covers the activation methods, internal architecture, and configuration files within the JuliusBrussee/caveman repository.

What is Wenyan Mode?

Wenyan mode transforms standard responses into classical Chinese (文言文) through three distinct intensity levels defined in skills/caveman/SKILL.md. Each level applies different compression rules:

• wenyan-lite: Preserves most grammatical structure while substituting key terms with classical equivalents.
• wenyan-full: Reorders clauses and replaces modern phrasing with idiomatic classical Chinese.
• wenyan-ultra: Applies maximum compression, stripping filler words and inserting classical particles (之, 乃, 為, 其) for the most terse output.

According to lines 39-41 of skills/caveman/SKILL.md, these levels provide 80-90% token reduction compared to standard English responses.

Activating Wenyan Mode

Using Slash Commands

The simplest way to enable Wenyan mode is through the /caveman slash command defined in commands/caveman.md. The command accepts the following Wenyan variants:

/caveman wenyan-lite     # Light compression, keeps grammar structure

/caveman wenyan-full     # Full classical Chinese transformation

/caveman wenyan-ultra    # Maximum compression, minimal tokens

When you issue /caveman wenyan-full, the system processes the argument through the plugin layer. In src/plugins/opencode/plugin.js (lines 127-153), the alias "wenyan-full" normalizes to the canonical label "wenyan", which src/hooks/caveman-mode-tracker.js stores as the active session mode (line 56).

The mode persists for the entire session unless you issue another /caveman command or explicitly disable it with /caveman off.

Programmatic Activation

For automated scripts or external integrations, you can enable Wenyan mode by writing directly to the mode flag file. The configuration helper in src/hooks/caveman-config.js defines the MODE_FLAG_PATH constant, typically resolving to ~/.caveman/mode.flag.

import { writeFileSync } from 'fs';
import path from 'path';

// Path defined by MODE_FLAG_PATH in src/hooks/caveman-config.js
const flagPath = path.join(process.env.HOME, '.caveman', 'mode.flag');

// Activate wenyan-ultra mode programmatically
writeFileSync(flagPath, 'wenyan-ultra', 'utf8');
console.log('Wenyan-ultra mode enabled');

Note that src/hooks/caveman-config.js (line 24) validates the mode string against allowed values including "wenyan-lite", "wenyan", "wenyan-full", and "wenyan-ultra".

Internal Architecture

The Wenyan transformation pipeline involves four core components:

1. Command Interface (commands/caveman.md): Parses the slash command and arguments.
2. Alias Normalization (src/plugins/opencode/plugin.js): Maps user-friendly aliases to canonical mode labels.
3. State Management (src/hooks/caveman-mode-tracker.js): Tracks the active compression level per session.
4. Rule Engine (skills/caveman/SKILL.md): Contains the transformation tables and examples (lines 47-56) that govern how modern text converts to classical Chinese.

When active, the response generator applies rules from skills/caveman/SKILL.md before sending output, swapping standard phrasing for classical Chinese idioms.

Expected Output and Token Savings

When Wenyan mode is active, technical explanations compress dramatically. For example, asking "Explain database connection pooling" with /caveman wenyan-full active produces:

池蓄已開之連，不逐請而新開，省握手之費。

This classical Chinese sentence conveys the concept of reusing open connections rather than creating new ones for each request, achieving approximately 85% token reduction while preserving the technical meaning of database connection pooling.

Summary

• Wenyan mode in Caveman provides classical Chinese compression through three intensity levels: wenyan-lite, wenyan-full, and wenyan-ultra.
• Activate via /caveman commands or programmatically by writing to the mode flag file at ~/.caveman/mode.flag.
• The pipeline processes commands through src/plugins/opencode/plugin.js, stores state in src/hooks/caveman-mode-tracker.js, and validates against src/hooks/caveman-config.js.
• Transformation rules live in skills/caveman/SKILL.md and reduce token counts by 80-90%.

Frequently Asked Questions

What is the difference between wenyan-lite, wenyan-full, and wenyan-ultra?

According to skills/caveman/SKILL.md (lines 39-41), wenyan-lite preserves most modern grammar while substituting key terms, wenyan-full reorders clauses into classical syntax, and wenyan-ultra applies maximum compression by stripping filler words and inserting classical particles (之, 乃, 為, 其) for the most terse output possible.

How do I disable Wenyan mode once enabled?

Type /caveman off in the chat interface. This command clears the active mode from the session tracker in src/hooks/caveman-mode-tracker.js and reverts responses to standard formatting.

Can I use Wenyan mode in automated scripts?

Yes. Scripts can write the desired mode string directly to the flag file at ~/.caveman/mode.flag (defined by MODE_FLAG_PATH in src/hooks/caveman-config.js). Valid values include wenyan-lite, wenyan, wenyan-full, and wenyan-ultra as enumerated in line 24 of the config file.

Where are the Wenyan compression rules defined?

The transformation specifications and example mappings reside in skills/caveman/SKILL.md, specifically in the table at lines 39-41 and the concrete examples at lines 47-56. This file drives the rule engine that converts modern technical text into classical Chinese.

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