# How Wenyan Levels Achieve Additional Compression Using Classical Chinese in Caveman

> Discover how Wenyan levels in JuliusBrussee/caveman achieve 80-90% compression using Classical Chinese grammar. Learn how this reduces tokens for efficient data handling.

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

---

**The Wenyan levels in the Caveman skill harness Classical Chinese (文言文) grammar—eliminating subjects, condensing particles into single characters like 之 and 乃, and leveraging lexical density—to achieve 80–90% character reduction, which translates directly into fewer tokens since each Chinese character typically maps to a single token.**

The Caveman repository (`JuliusBrussee/caveman`) implements a novel text compression strategy through its specialized "Wenyan" intensity levels. Unlike standard token-dropping heuristics, these levels (`wenyan-lite`, `wenyan-full`, `wenyan-ultra`) utilize Classical Chinese syntax to minimize character count. This article examines how the source code implements this linguistic compression and why it outperforms English-based minification.

## Architectural Overview of the Wenyan Pipeline

The Wenyan compression system spans three core components: the mode registry, skill definition, and flag persistence layer.

### Mode Registry and Flag Resolution

In [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js), the system declares eight supported Wenyan aliases including `wenyan-lite`, `wenyan`, `wenyan-full`, and `wenyan-ultra` (lines 22-25). The [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) hook resolves these aliases to canonical labels (`wenyan` ↔ `wenyan-full`) that the runtime uses to select the appropriate prompt template.

The flag handling logic (lines 90-109 in [`caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-config.js)) persists the chosen level across sessions, ensuring that the Classical Chinese style guide remains active for subsequent turns.

### Skill Definitions and Prompt Engineering

The actual compression instructions reside in [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) (lines 34-41). This file stores human-readable descriptions of each intensity level and provides concrete example sentences. When a Wenyan level is active, the skill injects these examples into the LLM prompt (lines 47-49), instructing the model to mimic Classical Chinese patterns rather than standard English phrasing.

## Linguistic Mechanisms Behind the Compression

Classical Chinese achieves its compression through five specific grammatical strategies that eliminate redundant tokens.

- **Verb-Object Ordering**: Classical syntax places verbs before objects without auxiliary prepositions, collapsing phrases like "wrap it with useMemo" into "useMemo 包之".

- **Subject Omission**: When context is clear, subjects are dropped entirely, removing entire noun phrases from the output.

- **Particle Economy**: Single characters such as 之, 乃, 為, and 其 replace multi-word English clauses ("the...that..."), reducing token count dramatically.

- **Lexical Density**: Single characters convey concepts requiring multiple English words; for example, "重繪" represents "re-render" in two characters versus twelve in English including spaces.

- **Fixed-Phrase Concision**: Classical idioms compress complex technical concepts. The phrase "池蓄已開之連" ("pool stores already-opened connections") replaces the full English explanation "Pool reuse open DB connections. No new connection per request."

## Concrete Examples: English vs. Wenyan Output

The [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) file documents practical translations that demonstrate the 80–90% character reduction. Consider these React and database examples:

Standard English output:

```javascript
// Full English (caveman-full)
"New object ref each render. Wrap it in useMemo."

```

Wenyan-full output:

```text
每繪新生對象參照，故重繪；以 useMemo 包之則免。

```

Database connection pooling:

```text
// Wenyan-full
池蓄已開之連，不逐請而新開，省握手之費。

// Wenyan-ultra (minimalist)
新參照則重繪。useMemo 包之。

```

## Why This Reduces Token Count

Modern LLM tokenizers, such as those used by OpenAI models, typically assign one token per Chinese character while English words often split into multiple subword tokens (e.g., "rendering" might become two tokens). By compressing meaning into dense Classical Chinese characters, the Wenyan levels minimize the total token sequence length. According to the [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) documentation, this yields an 80–90% character reduction over full English style, with proportional token savings.

## Summary

- The Wenyan levels (`wenyan-lite`, `wenyan-full`, `wenyan-ultra`) are defined in [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) and activated via flags in [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js).
- Classical Chinese compression relies on subject omission, particle economy, and lexical density to minimize character count.
- Specific examples show React concepts like "re-render" compressed from multi-word English phrases into single-character compounds like "重繪".
- Because tokenizers treat each Chinese character as approximately one token, the 80–90% character reduction translates directly to significant token savings.

## Frequently Asked Questions

### What is the difference between wenyan-full and wenyan-ultra?

The `wenyan-full` level produces complete Classical Chinese sentences with proper grammatical structure, while `wenyan-ultra` strips the output to the barest grammatical skeleton. For example, `wenyan-full` might produce "每繪新生對象參照，故重繪；以 useMemo 包之則免" (full explanation), whereas `wenyan-ultra` collapses this to "新參照則重繪。useMemo 包之" (minimal subject-only phrases).

### How does the system know which Wenyan level to use?

The active level is read from a flag file by the hook in [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) (lines 90-109), which validates the mode against the registry of eight supported aliases (lines 22-25). The resolved value determines which examples from [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) get injected into the LLM prompt.

### Why does Classical Chinese reduce tokens more effectively than English abbreviations?

English abbreviations often retain word boundaries and grammatical particles that still consume tokens, whereas Classical Chinese eliminates subjects and auxiliary words entirely while using single-character particles (之, 乃) to replace multi-word clauses. Since tokenizers map each Chinese character to roughly one token compared to multiple tokens per English word, the character-density advantage translates directly to token savings.

### Can I use Wenyan levels with programming languages other than JavaScript?

Yes. The Wenyan compression is language-agnostic; it operates on the natural language explanation of code rather than the code syntax itself. The examples in [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) include database connection pooling and React patterns, but the Classical Chinese style guide applies to any technical description the LLM generates.