UltraPress saves context window tokens through 4 compression layers that run automatically in the background — from CLI output filtering, semantic compression, dynamic context pruning, to auto-cleanup. Your LLM stays smart, tokens stay lean.

📑 Table of Contents

• ⚡ Installation & Setup
  • System Requirements
  • Install from GitHub
  • Register to OpenCode
  • Personal Configuration
  • Verify Installation
  • Uninstall
• 🛠 4-Layer Architecture
  • Pipeline Flow
  • Layer 1 — Smart Output Filter
  • Layer 2 — GSC Semantic Compression
  • Layer 3 — Dynamic Context Pruning (DCP)
  • Layer 4 — Session Auto-Cleanup
• ⚙️ Configuration
  • Full documentation →
• ⌨️ /up Slash Command
  • Sub-command List
  • Example Output
• ❷ MLM & NLP Support
  • NLP Mode (Default)
  • MLM Mode (Experimental)
  • Mode Comparison
• 🏗 Code Architecture
  • Directory Structure
  • Hook Registration Map
  • Data Flow Detail
• 🧪 Testing
• 📊 Benchmark
• 🚀 Local Development
• ❓ FAQ & Troubleshooting
• 🗺 Roadmap
• 🤝 Contributing
• 📝 Changelog
• 📄 License

⚡ Installation & Setup

System Requirements

Compatibility Matrix (Runtime)

Legend: ✅ recommended · ⚠️ possible but resource-sensitive

Cross-Platform Notes

UltraPress is pure TypeScript and works across all platforms OpenCode supports:

• macOS
• Linux
• WSL / Termux
• Windows

What to expect:

• mlm / llm modes may download model assets on first use (larger disk/RAM footprint).
• If your environment is resource-limited (e.g., small VPS/Termux), use default Balanced (NLP) or force semantic.mode: "nlp" for zero-model operation.

1. Install the Plugin

# ✅ RECOMMENDED — auto-registers with OpenCode
opencode plugin add @rahadiana/opencode-ultrapress@latest --global

⚠️ Important: OpenCode caches the plugin at ~/.cache/opencode/packages/. @latest is resolved once on first install — subsequent versions won't auto-update. To upgrade:

rm -rf ~/.cache/opencode/packages/@rahadiana/opencode-ultrapress@latest
opencode plugin add @rahadiana/opencode-ultrapress@latest --global

The plugin will warn you at startup if a newer version is available.

Alternative install methods (not recommended for end users):

# Via npm — requires manual registration (step 2), same cache caveat applies
npm install -g @rahadiana/opencode-ultrapress

# GitHub latest — for testing pre-release changes
npm install -g github:rahadiana/opencode-ultrapress

For plugin development:

git clone https://github.com/rahadiana/opencode-ultrapress.git
cd opencode-ultrapress
npm install
npm run build

# Link globally so OpenCode can find it
npm link

# Then in OpenCode's config (~/.config/opencode/config.json), add:
# { "plugins": ["@rahadiana/opencode-ultrapress"] }
#
# After making code changes, re-run:
# npm run build
#
# No need to re-link — OpenCode loads from the linked directory.
# If using opencode plugin add, remove the cached version first:
# rm -rf ~/.cache/opencode/packages/@rahadiana/opencode-ultrapress@latest

2. Register to OpenCode (npm install only)

If you installed via opencode plugin, skip this step — registration is automatic.

Add the plugin to OpenCode's config at ~/.config/opencode/config.json:

{
  "plugins": ["@rahadiana/opencode-ultrapress"]
}

3. (Optional) Create Personal Configuration

UltraPress works out-of-the-box with Balanced defaults. For customization:

# Install from GitHub → copy from the cloned repo
cp ultrapress.plugin.jsonc.example ~/.config/opencode/ultrapress.plugin.json

# Or from global install
cp $(npm root -g)/@rahadiana/opencode-ultrapress/ultrapress.plugin.json.example ~/.config/opencode/ultrapress.plugin.json

Then edit ~/.config/opencode/ultrapress.plugin.json as needed. If the file is not found, UltraPress will automatically create it with default values on first run.

Quick-Start Profiles by Device

Use this as a practical starting point:

Minimal override examples:

// Low-resource profile
{
  "semantic": { "mode": "nlp" }
}

// Higher-quality semantic profile (requires more RAM)
{
  "semantic": {
    "mode": "mlm",
    "model": "Xenova/all-MiniLM-L6-v2"
  }
}

Verify Installation

Restart OpenCode, then type in chat:

/up stats

If a statistics dashboard appears, UltraPress is active. If not:

1. Installed via npm install? Make sure the plugin is in config.json → "plugins": ["@rahadiana/opencode-ultrapress"]
2. Installed via opencode plugin? Run opencode plugin list to confirm it's registered.
3. Check OpenCode logs for errors
4. Ensure Node.js >= 18 is installed (node --version)

Uninstall

# 1. Remove from OpenCode plugin list
#    Edit ~/.config/opencode/config.json — remove "@rahadiana/opencode-ultrapress" from plugins array

# 2. Purge the cached version
rm -rf ~/.cache/opencode/packages/@rahadiana/opencode-ultrapress@latest

# 3. If installed via npm (global)
npm uninstall -g @rahadiana/opencode-ultrapress

# 4. If using npm link
npm unlink -g @rahadiana/opencode-ultrapress

# 5. Clean up config
rm ~/.config/opencode/ultrapress.plugin.json

🛠 4-Layer Architecture

UltraPress intercepts OpenCode message flow at 4 different points, each with a specific compression strategy.

Pipeline Flow

flowchart LR
    A([Tool Output]) -->|"tool.execute.after"| L1[Layer 1\nOutput Filter]
    B([Chat Message]) -->|"chat.message"| PRUNE{Prune\nPending?}
    PRUNE -->|yes| REMOVE[Remove msgs\n& inject summary]
    PRUNE -->|no| L2[Layer 2\nGSC Semantic]
    REMOVE --> L2
    L2 --> L3[Layer 3\nNudge Monitor]
    L3 -->|"nudge injected"| LLM{LLM}
    LLM -->|"calls tool"| DCP_TOOL[ultrapress_compress]
    DCP_TOOL -.->|"block stored"| PRUNE
    D([Session Compact]) -->|"session.compacting"| L4[Layer 4\nCleanup]

    L1 & L2 & L4 --> CTX[(Context\nWindow)]

Layer 1 — Smart Output Filter

Hook: tool.execute.after · File: layer1-output-filter.ts · Filters: src/filters/

Intercepts CLI tool output before it enters the context window. The most aggressive layer — directly cuts unnecessary logs.

Core Strategies:

Built-in Filters:

Layer 2 — GSC Semantic Compression

Hook: chat.message · File: layer2-caveman.ts · Engine: src/caveman/

Compresses message text semantically — removes unimportant words without changing meaning. Layer 2 and Layer 3 do not compress each other — no double compression.

Compression Rules:

• Conjunctions (that, and, will, which) → removed
• Excessive pronouns → condensed
• Redundancy ("I think I will" → "I will") → removed
• Double spaces, unnecessary whitespace → normalized
• Code blocks (inside ```) → NEVER touched
• Error messages & stack traces → fully protected
• Messages < 200 characters → skipped

Operating Modes:

See ❷ MLM & NLP Support for detailed NLP vs MLM comparison.

Layer 3 — Dynamic Context Pruning (DCP)

Hook: chat.message (pruning) + tool.execute.after (compress tool) · File: layer3-dcp.ts · Engine: src/dcp/

The most advanced system: gives LLM autonomy to manage its own memory. Unlike Layer 2 which only compresses text, Layer 3 actually removes old messages from the context window and replaces them with summaries.

Mechanism:

1. Context Monitor → detect tokens approaching maxContextLimit
2. Autonomous Nudge → inject prompt into user message: "context window nearly full, call ultrapress_compress"
3. LLM calls → ultrapress_compress(mode="range", from=<id>, to=<id>)
4. Compression Block → stored in memory (compress-state.ts)
5. chat.message hook → check pending blocks → remove messages in range → inject summary as synthetic message

Key Features:

Two Pruning Modes:

Layer 4 — Session Auto-Cleanup

Hook: tool.execute.after + session.compacting · File: layer4-cleanup.ts

Automatically cleans "garbage" from the context window.

Features:

⚙️ Configuration

📖 Full configuration documentation (all keys, types, defaults, examples, presets, custom filters, troubleshooting) at: docs/konfigurasi-lengkap.md

Basic Structure

File: ~/.config/opencode/ultrapress.plugin.json

{
  "enabled": true,           // Master switch
  "notification": "minimal", // "off" | "minimal" | "detailed"

      "outputFilter": {},
      "semantic": {},
      "summarization": {},
      "cleanup": {}
}

🔒 Safety guard: task is always enforced in outputFilter.skipTools and semantic.skipTools even if removed in user config. This prevents accidental sub-agent context loss.

👉 Open full documentation → covers all keys, types, defaults, custom filters, presets (Balanced / Aggressive / Conservative / NLP-only), and troubleshooting.

⌨️ /up Slash Command

All interactions with UltraPress via a single command: /up.

Sub-command List

Note: Sub-commands are case-insensitive and support partial fuzzy matching.

Example Output

/up stats:

📊 ULTRAPRESS STATS
──────────────────────────────────────────
  Raw tokens       : 127,450
  Compressed tokens: 89,215
  Tokens saved     : 38,235 (30.0%)

  By Layer:
  L1 Output Filter : 18,400
  L2 Semantic      : 12,100
  L3 Summarization :  5,835
  L4 Cleanup       :  1,900

  Activity:
  Compressions : 3
  Deduplications: 12
  Errors purged: 2

  Session: 2h 15m
──────────────────────────────────────────

/up context:

🧠 CONTEXT STATUS
──────────────────────────────────────────
  Current tokens     : ~52,000
  Max context limit  : 70,000
  Available          : ~18,000 (25.7%)
  Nudge threshold    : 40,000
  Status             : 🟡 Nearing limit (nudge will fire soon)
  Next nudge in      : 3 turns
──────────────────────────────────────────

❷ MLM & NLP Support

NLP Mode (Default)

Rule-based grammar stripping using linguistic rules. Zero latency, no external model required.

How it works:

1. Detect sentence structure (subject, predicate, object)
2. Remove conjunctions, excessive pronouns, filler words
3. Condense redundancy without changing meaning
4. Protect code blocks & error messages

MLM Mode (Experimental)

Uses Masked Language Model via @huggingface/transformers (Transformers.js) for more accurate tokenization.

Activation:

{
  "semantic": {
    "mode": "mlm",
    "model": "Xenova/distilbert-base-uncased"
  }
}

Important Notes:

• ⚠️ Model auto-downloaded on first run (~70MB for distilbert-base)
• ⚠️ First-run latency 5-15 seconds for model loading
• ⚠️ RAM usage increases ~200MB when model is active
• ⚠️ Compatibility: CPU-only (no GPU required)
• 🌐 For Indonesian: use Xenova/bert-base-multilingual-uncased

Mode Comparison

🏗 Code Architecture

Directory Structure

opencode-ultrapress/
├── src/
│   ├── index.ts                    # Entry point, hook registration, plugin server
│   ├── config/
│   │   ├── schema.ts               # TypeScript type definitions (UltraPressConfig, etc.)
│   │   └── defaults.ts             # Default config values + merge logic
│   ├── layers/
│   │   ├── layer1-output-filter.ts # RTK engine — routes tool output to domain filters
│   │   ├── layer2-caveman.ts       # Semantic compression orchestrator
│   │   ├── layer3-dcp.ts           # DCP orchestrator — nudge injection, pruning trigger
│   │   └── layer4-cleanup.ts       # Auto-cleanup — dedup + error purging
│   ├── filters/
│   │   ├── git.ts                  # Git-specific output filter
│   │   ├── test.ts                 # Test runner output filter
│   │   ├── bash.ts                 # Shell output filter
│   │   ├── fs.ts                   # Filesystem tool output filter
│   │   └── generic.ts              # Fallback filter
│   ├── dcp/
│   │   ├── compress-state.ts       # In-memory state for pending compression blocks
│   │   ├── compress-tool.ts        # ultrapress_compress tool definition & handler
│   │   ├── context-monitor.ts      # Token usage monitoring + nudge logic
│   │   ├── prune.ts                # Message removal + summary injection engine
│   │   ├── protected-content.ts    # Defines which tool outputs are protected
│   │   └── summary-store.ts        # Stores summaries for nesting support
│   ├── caveman/
│   │   ├── nlp.ts                  # Rule-based NLP compressor
│   │   └── mlm.ts                  # MLM-based compressor (Transformers.js)
│   ├── commands/
│   │   └── slash.ts                # /up slash command handler
│   └── utils/
│       ├── token-count.ts          # Token estimation (char-based approximation)
│       └── logger.ts               # Logging with configurable verbosity
├── tests/
│   ├── layer1.test.ts              # Output filter unit tests
│   ├── layer2.test.ts              # Semantic compression unit tests
│   └── layer3-dcp.test.ts          # DCP pruning + nudge unit tests
├── benchmarks/
│   ├── run.ts                      # Benchmark runner
│   └── fixtures/                   # Benchmark test data
├── docs/
│   └── image/
│       └── banner.svg              # README banner
├── ultrapress.plugin.jsonc.example        # Configuration template (JSONC)
├── tsconfig.json                   # TypeScript config
├── tsup.config.ts                  # Build config (tsup)
├── package.json
├── CHANGELOG.md
├── LICENSE
└── README.md

Hook Registration Map

Data Flow Detail

1. Plugin Init
   config hook → register /up command
   tool definition → register ultrapress_compress
   load/migrate config from ~/.config/opencode/ultrapress.plugin.json

2. Tool Execution (every tool call)
   tool.execute.after → L1 processToolOutput()
     → Domain routing (git→git.ts, test→test.ts, etc.)
     → Middle-out truncation
     → Deduplication
   → L4 applyCleanup()
     → Dedup check
     → Error registration for purge

3. Chat Message (every user message)
   chat.message → L3 check pending compression blocks
     → applyPruning() — remove old messages, inject summaries
   → L2 processMessageContext() — semantic compression
   → L3 context monitor — check token count
     → if near limit → inject nudge prompt
   → L3 turnTick() — update turn counter

4. LLM calls ultrapress_compress
   tool.execute.after → compress tool handler
     → Create CompressionBlock in compress-state.ts
     → Store summary for nesting
   → Block will be executed on NEXT chat.message

5. Session Compacting
   session.compacting → L4 protected context injection

🧪 Testing

Run the entire test suite:

bun test

# Run specific layer
bun test tests/layer1.test.ts
bun test tests/layer2.test.ts
bun test tests/layer3-dcp.test.ts

# Run with TypeScript type checking
bun run lint

📊 Benchmark

Run the full benchmark to measure the effectiveness of all 4 layers:

npm run benchmark

Latest Benchmark Results

┌────────────────────────────────┬──────────────────────────────────────────┬────────────┬──────────────┬──────────┐
│Fixture                         │Layer                                     │Original    │Compressed    │Savings   │
├────────────────────────────────┼──────────────────────────────────────────┼────────────┼──────────────┼──────────┤
│git-diff-large.txt              │L1 — Git Filter                           │       1,657│           969│       42%│
│npm-install-log.txt             │L1 — Generic Filter                       │         431│           430│        0%│
│pytest-log.txt                  │L1 — Generic Filter                       │       1,200│         1,199│        0%│
│chat-history.json               │L2 — NLP Semantic                         │         625│           490│       22%│
│dcp-conversation.json           │L3 — DCP Pruning (14→summary)             │       2,347│           645│       73%│
│                                │  ↳ 10 msg removed, 1 summary injected    │            │              │          │
│3x identical npm test           │L4 — Tool Call Dedup                      │       2,244│           854│       62%│
│                                │  ↳ 2 duplicates collapsed                │            │              │          │
│5 errors × 6 turns              │L4 — Error Auto-Purge                     │         845│             0│      100%│
│                                │  ↳ 5 errors purged after threshold       │            │              │          │
└────────────────────────────────┴──────────────────────────────────────────┴────────────┴──────────────┴──────────┘

✅ Total: 9,349 → 4,587 tokens (51% overall savings)

Layer Summary

💡 Insight: L3 (DCP) is the layer with the highest savings because it removes old messages in bulk. In long sessions (100+ messages), the cumulative effect of L3 + L4 can reach 70-90% token savings. Dataset and scripts are in benchmarks/ — contribute fixtures from your stack for more representative results.

🚀 Local Development

# 1. Clone repository
git clone https://github.com/rahadiana/opencode-ultrapress.git
cd opencode-ultrapress

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build          # tsup — compile to dist/

# 4. Development mode (watch)
npm run dev            # tsup --watch

# 5. Run tests
npm test               # bun test

# 6. Type checking
npm run lint           # tsc --noEmit

# 7. Benchmark
npm run benchmark      # tsx benchmarks/run.ts

Development Workflow:

1. Edit files in src/
2. npm run dev for auto-rebuild
3. npm test to verify
4. Restart OpenCode to reload plugin
5. Test via /up stats in chat

❓ FAQ & Troubleshooting

npm install -g @huggingface/transformers

{
  "semantic": { "enabled": false },
  "summarization": { "enabled": false }
}

npm install
npm run lint    # tsc --noEmit to check for type errors

🗺 Roadmap

🤝 Contributing

Contributions are welcome! Areas most in need of help:

1. New Filters: Add Layer 1 filters for new frameworks/stacks (Kubernetes, Docker, Terraform, Svelte, Flutter, etc.).
2. MLM Roadmap: Help implement actual TF-IDF scoring or sentence similarity.
3. Benchmark Dataset: Contribute fixture data from your tech stack.
4. Multi-language NLP: Expand grammar stripping rules for more languages.
5. Bug Reports: Report edge cases — poorly filtered tool output, important messages deleted, etc.

Development Setup

git clone https://github.com/rahadiana/opencode-ultrapress.git
cd opencode-ultrapress
npm install
npm run build
npm test
npm run benchmark

Pull Request Process

1. Fork repository
2. Create feature branch (git checkout -b feature/amazing-filter)
3. Commit changes (git commit -m 'Add amazing filter')
4. Push to branch (git push origin feature/amazing-filter)
5. Open Pull Request — ensure bun test and npm run lint pass

📝 Changelog

See CHANGELOG.md for the full version history.

📄 License

MIT © rahadiana