UltraPress — 4-Layer Token Compression for OpenCode AI

UltraPress is an OpenCode AI plugin that compresses conversation context in real-time using a 4-layer pipeline. It intercepts tool outputs, chat messages, and compaction events to reduce token consumption without losing critical information.

Quick Start

# In OpenCode chat:
/up enable          # Enable compression
/up stats           # View compression statistics
/up config          # View current configuration

Installation

# From npm (published package)
npm install -g @rahadiana/opencode-ultrapress
# Then add to opencode.json as a plugin

# From local clone
cd opencode-ultrapress
npm install
npm run build
# Add as local plugin in opencode.json:
# { "type": "plugin", "path": "/path/to/opencode-ultrapress" }

Note: After upgrading, run npm run build and restart OpenCode. If OpenCode caches the old plugin, clear the cache or reinstall.

Build / Test Commands

npm install       # Install deps (npm lockfile)
npm run lint      # Typecheck (tsc --noEmit)
npm test          # Run tests (bun test)
npm run build     # Build dist/ (tsup, ESM + d.ts)
npm run benchmark # Run benchmarks (tsx benchmarks/run.ts)

Architecture

Pipeline: L1 Filter → L2 Semantic → L3 DCP → L4 Cleanup

Each layer targets a different compression opportunity:

Hook Registration (src/index.ts)

command.execute.before          → /up command + config persistence
tool.execute.after              → L1 filtering + L4 cleanup
chat.message                    → Token sync + L2/L3 + post-command suppression
experimental.chat.messages.transform → Strip mode-injection artifacts
experimental.session.compacting → Inject protected context during compaction

Custom tools registered: ultrapress_compress, ultrapress_expand

Layer Details

L1 — Output Filter (src/layers/layer1-output-filter.ts)

Intercepts tool outputs and applies command-specific filters:

• Bash: Detects build/docker/grep/generic commands — keeps only errors, warnings, final status
• Git: status → compact file list, diff → changed lines only, log → one-liners, add/commit/push → summary
• Filesystem: ls/find/tree/cat — dedup, group by directory, limit per file
• Test runners: Jest/Vitest/Pytest/Cargo/Bun — failures + summary only, strips pass lines
• Generic fallback: Strip ANSI, dedup lines, collapse blanks, smart truncate (head 70% + tail 25%)

Config: maxCharsPerOutput (default 6000), skipTools, teeSaveOnTruncate, custom regex filters.

L2 — Semantic (src/layers/layer2-caveman.ts, src/caveman/)

NLP-based compression with 3 modes:

All modes protect code blocks (``` fences) and error messages from compression.

L3 — DCP (src/layers/layer3-dcp.ts, src/dcp/)

Adaptive context compression. Decides WHEN to compress via:

1. Scorer (scorer.ts): Scores each message by purpose, recency, and role
2. Pruner (prune.ts): Selects stale candidates, groups into batches
3. Compress State (compress-state.ts): Generates high-fidelity summaries
4. Storage (storage.ts): Persists compressed content for expansion via ultrapress_expand

Token-aware: auto-compress only when batch ≥ 5 messages to avoid wasting tokens on tiny blocks.

L4 — Cleanup (src/layers/layer4-cleanup.ts)

Post-filter cleanup: deduplicates consecutive identical tool calls, purges stale error messages after N turns.

Commands

All commands are prefixed with /up:

Stats Display Example

UltraPress Session Stats
========================
Total Messages  : 140
Sent Messages   : 55
Received        : 85
Total Original  : 670.0k
Total Compressed: 261.9k
Overall Savings : 408.1k (+61%)

── Layer Breakdown ──
L1 (Output Filter)
  120 tools filtered, saved 46.2k
L2 (Semantic)
  30 messages, saved 175.9k
L3 (Summary)
  95 compressions, saved 40.6M (accumulated)
L4 (Cleanup)
  25 tools deduped, saved 61.5k

Total Tool Calls Filtered  : 120
Total Semantic Compressions: 30
Total DCP Compressions     : 95
Total Deduplications       : 25

real session tokens may vary due to repeated compression by platform

Configuration

Config is persisted in ~/.config/opencode/ultrapress/storage/config.json.

{
  "enabled": true,
  "enableDebug": false,
  "outputFilter": {
    "enabled": true,
    "maxCharsPerOutput": 6000,
    "teeSaveOnTruncate": true,
    "skipTools": ["task"],
    "customFilters": []
  },
  "semantic": {
    "enabled": true,
    "mode": "nlp",
    "model": "",
    "compressUserMessages": true,
    "compressAssistantMessages": true,
    "compressToolOutputs": true,
    "protectCodeBlocks": true,
    "protectErrors": true,
    "skipTools": ["task"]
  },
  "summarization": {
    "enabled": true,
    "minMessagesForCompression": 10,
    "batchThreshold": 5,
    "maxBatchSize": 12,
    "contextLines": 3,
    "memoryLimit": 300
  },
  "cleanup": {
    "enabled": true,
    "deduplication": { "enabled": true },
    "purgeErrors": { "enabled": true, "turns": 5 }
  },
  "commands": { "enabled": true },
  "notification": "minimal"
}

Set via /up config:

/up config outputFilter.maxCharsPerOutput=4000
/up config semantic.mode=llm
/up config notification=detailed

Full schema: ultrapress.schema.json

Development History (Changelog)

File Map

src/
├── index.ts                        # Plugin entry, hook registration
├── commands/
│   └── slash.ts                    # /up command handler + stats display
├── config/
│   ├── defaults.ts                 # Default configuration values
│   ├── schema.ts                   # TypeScript types & runtime schema
│   └── validate.ts                 # Config sanitization & validation
├── layers/
│   ├── layer1-output-filter.ts     # L1: Tool output filtering
│   ├── layer2-caveman.ts           # L2: Semantic compression
│   ├── layer3-dcp.ts               # L3: DCP conversation compression
│   └── layer4-cleanup.ts           # L4: Dedup & error purge
├── caveman/
│   ├── nlp.ts                      # TF-IDF sentence scoring
│   ├── mlm.ts                      # Transformers.js embeddings
│   ├── llm.ts                      # LLM-based summarization
│   ├── rules.ts                    # Compression rules & heuristics
│   └── facts.ts                    # Fact extraction utilities
├── dcp/
│   ├── scorer.ts                   # Message importance scoring
│   ├── prune.ts                    # Stale message selection
│   ├── compress-state.ts           # Summary generation logic
│   ├── compress-tool.ts            # ultrapress_compress tool
│   ├── expand-tool.ts              # ultrapress_expand tool
│   ├── storage.ts                  # Compressed content persistence
│   ├── context-monitor.ts          # Context size monitoring
│   └── protected-content.ts        # Content protection during compression
├── cleanup/
│   ├── dedup.ts                    # Consecutive identical tool call dedup
│   └── purge-errors.ts             # Stale error message purging
├── filters/
│   ├── bash.ts                     # Shell command output filters
│   ├── git.ts                      # Git command output filters
│   ├── fs.ts                       # Filesystem command filters
│   ├── test.ts                     # Test runner output filters
│   └── generic.ts                  # Universal smart filter
└── utils/
    ├── logger.ts                   # Debug logging
    └── token-count.ts              # Token counting (tiktoken-like)

Project Files