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

> Learn to use Wenyan mode in Caveman to compress replies into classical Chinese. Reduce token usage by up to 90% with wenyan-full, wenyan-lite, or wenyan-ultra commands.

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

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.md). The command accepts the following Wenyan variants:

```text
/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) defines the `MODE_FLAG_PATH` constant, typically resolving to `~/.caveman/mode.flag`.

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.md)): Parses the slash command and arguments.
2. **Alias Normalization** ([`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)): Maps user-friendly aliases to canonical mode labels.
3. **State Management** ([`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)): Tracks the active compression level per session.
4. **Rule Engine** ([`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js), stores state in [`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js), and validates against [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js).
- Transformation rules live in [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.