OpenCode Context Optimizer (OCCE)

Context optimization & token-saving MCP server for OpenCode CLI, Claude Code, and Cursor.
Cut prompt token burn by 75% to 90% on free-tier models (Big Pickle, MiMo, Qwen, DeepSeek) to prevent sliding-window rate limit lockouts and eliminate "lost-in-the-middle" attention degradation.

The Problem: The Agent Loop Multiplier

When using OpenCode CLI with free models routed through the OpenCode Zen gateway (big-pickle, mimo-v2.6-flash-free), models are governed by:

1. Sliding-Window Rate Limits: Server-side quotas tracking in-flight and rolling prompt token volume. Crossing the threshold triggers sudden Rate limit exceeded lockouts lasting hours to 24–48 hours.

2. Attention Degradation ("Lost in the Middle"): Beyond 32,000–50,000 tokens, free open-weight models begin hallucinating line offsets, repeating tool calls, and dropping system prompt guidelines.

3. The Agent Loop Multiplier: In an autonomous coding agent, every intermediate tool execution (read_file $\to$ bash $\to$ edit $\to$ pytest) re-transmits the entire cumulative session history.

Standard OpenCode 6-Turn Bug-Fix Loop:
Turn 1: Prompt + Read file (450 LOC) ──────>  5,000 prompt tokens
Turn 2: Run pytest (50 passing tests) ─────>  8,000 prompt tokens
Turn 3: Read helper module (300 LOC) ──────> 10,400 prompt tokens
Turn 4: Edit file patch ───────────────────> 11,600 prompt tokens
Turn 5: Re-run pytest ─────────────────────> 14,600 prompt tokens
Turn 6: Final answer ──────────────────────> 15,200 prompt tokens
──────────────────────────────────────────────────────────────────
CUMULATIVE TOKENS INGESTED BY ZEN GATEWAY:   51,100 TOKENS (Quota Saturated!)

With OCCE, the exact same 6-turn loop consumes ~6,800 cumulative tokens (86.7% overall reduction).

Related MCP server: mcp-context-condenser

Core Tools

OCCE exposes 6 specialized tools adhering to the Model Context Protocol (MCP):

Quantified Benchmarks

Measured on realistic Python, Go, and TypeScript repositories:

Architecture: Dual-Layer Defense (MCP + Companion Plugin)

OCCE operates across two coordinated layers:

1. Precision MCP Server (occe/server.py):

   • Zero-dependency Python server exposing 6 precision tools over stdio (code_skeleton, symbol_slice, smart_exec, test_compress, diff_compact, token_ledger).

   • Polyglot support: AST-based for Python; heuristic block slicing for TypeScript, TSX, JavaScript, JSX, Go, and Rust.

   • Resilient workspace resolution: Automatically consumes rootPath and rootUri handshakes per MCP (2024-11-05) standard.

2. OpenCode Companion Plugin (plugins/occe-guard.js):

   • Hot-reloaded directly into OpenCode 2.x runtimes without restarting CLI sessions.

   • Pre-execution hook (execute.before): Intercepts unconstrained file dumps and guides agents toward precision AST tools.

   • Post-execution hook (execute.after): Strips ANSI sequences, collapses 100% passing test suites (pytest, cargo, jest/vitest), and applies head/tail truncation on verbose logs (>70 lines), glob dumps (>40 paths), and grep search floods (>35 matches).

   • Session context hook (context, compaction, generate): Injects high-signal steering guidelines directly into event.system before each inference turn.

Quickstart & Setup

OCCE runs on standard Python 3.10+ with zero external dependencies.

1. Installation

Clone the repository:

git clone https://github.com/SammySN-car/opencode-context-mcp.git
cd opencode-context-mcp

2. Configure OpenCode CLI (opencode.jsonc)

Add OCCE to your project's opencode.jsonc (or global ~/.config/opencode/config.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context-optimizer": {
      "command": "python",
      "args": ["-m", "occe.server"]
    }
  },
  // Optional: Restrict built-in tools to guide model toward OCCE precision tools
  "permission": {
    "read": "deny",      // Prompts agent to use code_skeleton / symbol_slice
    "bash": "ask"        // Prompts agent to use smart_exec / test_compress
  }
}

3. Configure Claude Code / Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "context-optimizer": {
      "command": "python",
      "args": ["-m", "occe.server"]
    }
  }
}

OpenCode Companion Plugin (occe-guard.ts)

For users who prefer 100% transparent optimization without changing prompt habits, OCCE includes a companion plugin hook.

Copy plugins/occe-guard.ts into .opencode/plugins/:

• Automatically sanitizes native bash tool output (stripping ANSI codes and collapsing test passes).

• Automatically monitors native read calls on files $>250$ lines and inserts a token-budget reminder.

Architecture

flowchart TD
    Client["OpenCode CLI / Claude Code / Cursor"] -- "JSON-RPC 2.0 (stdio)" --> Server["OCCE MCP Server (occe/server.py)"]

    subgraph OCCE["OpenCode Context Engine"]
        Server --> Router{"Tool Router"}
        Router --> Skeletons["AST Engine\n(ast_skeleton.py)"]
        Router --> NoiseGate["Noise-Gate Pipeline\n(noise_gate.py)"]
        Router --> TestReducers["Test Reducers\n(test_reducers.py)"]
        Router --> DiffEngine["Zero-Context Diff\n(diff_engine.py)"]

        Server --> Ledger["Token Ledger & Health Monitor\n(ledger.py)"]
        Server --> Tombstones["Tombstone Tracker\n(tombstone.py)"]
    end

    Skeletons --> Output["80-94% Token Reduction"]
    NoiseGate --> Output
    TestReducers --> Output
    DiffEngine --> Output
    Ledger --> Alerts["Attention Zone Alerts\n(GREEN / YELLOW / RED)"]

Running Tests

OCCE includes a comprehensive 57-test verification suite covering AST transformations, regex noise suppression, test parsing for 4 frameworks, and JSON-RPC wire protocol compliance:

# Install pytest if not already installed
pip install pytest

# Run all 57 tests
python -m pytest -v

License

MIT License. Built by Samar Nathani.