opencode-slim-system

Reduces per-request token overhead by replacing OpenCode's bundled system prompt and built-in tool descriptions with compact versions.

Saves ~1,400 tokens/request from the system prompt and ~8,300 tokens/request from tool descriptions — ~9,700 total tokens saved on every request.

How It Works

Two plugin hooks:

tool.definition

Fires once per tool per session. If the tool ID matches a slim description file in tool/{id}.txt, replaces the stock description with the slim version. All 17 built-in OpenCode tools (v1.15.x) are covered (some are conditional on experimental flags). Non-built-in tools (from plugins like Magic Context, PTY, AFT) are left untouched.

experimental.chat.system.transform

Fires when the system prompt is constructed. If the prompt looks like a bundled default (detected by markers like "best coding agent on the planet"), replaces it with the content of prompt/default.txt. The environment block (model info, working directory, date) is preserved.

Why a plugin hook is necessary: OpenCode's prompts are compiled into the binary as static imports (packages/opencode/src/session/system.ts — model matching chooses one of anthropic.txt, beast.txt, gpt.txt, gemini.txt, codex.txt, trinity.txt, kimi.txt, or default.txt). There is no built-in filesystem override — the ~/.config/opencode/prompt/ feature proposed in PR #7264 was closed without merging. The plugin hook is the only way to replace the system prompt for models that don't match Claude/GPT patterns.

What's Included

Sidebar Panel

Registered at sidebar order 899. Shows:

• Tools slimmed — count of covered built-in tools (green)
• ⬆ Update available — when npm has a newer version (warning color, with version number)
• plugin not loaded — shown briefly before the server plugin writes its status file (normal on first load)
• Update dialog — on first TUI start per version, shows current vs latest + GitHub releases link

Dismissed versions are persisted to ~/.local/state/opencode-slim-system/announced.json.

Status File

The server plugin writes /tmp/opencode-slim-system.json at startup:

{
  "plugin": "opencode-slim-system@1.1.6",
  "opencode": "1.15.12",
  "slimmed": 17,
  "tools": ["apply_patch", "bash", "edit", ...],
  "latest_version": "1.1.6"
}

The TUI sidebar polls this file every 5 seconds. It ignores stale files from a previous npm version (compares the embedded plugin version against its own installed version). When a fresh file appears after a session starts, the sidebar updates and a startup toast fires once.

latest_version appears after the background npm check completes (usually within 1-2 seconds). If a newer version exists, update_available: true is also written to the file and the sidebar shows an ⬆ indicator.

Configuration

Plugin options are set via the array syntax in opencode.jsonc:

{
  "plugin": [
    ["opencode-slim-system", { "exclude": ["websearch", "webfetch"] }]
  ]
}

exclude (optional)

Array of tool IDs to keep at their original stock descriptions. Useful if you prefer the full description for specific tools (e.g., read, websearch). All other built-in tools are slimmed.

Customization

System Prompt

Edit prompt/default.txt in the npm package:

~/.cache/opencode/packages/opencode-slim-system@latest/
  node_modules/opencode-slim-system/
    prompt/default.txt     ← edit this
    tool/{id}.txt          ← edit tool descriptions

After editing, clear the cache and restart for changes to take effect:

rm -rf ~/.cache/opencode/packages/opencode-slim-system@latest

Note: The cache persists across restarts — rm -rf is required every time you edit the shipped files. For persistent customization, fork this repo, publish your own npm package, and register it instead.

Tool Descriptions

Each tool/{id}.txt file corresponds to a tool ID from OpenCode's registry. Edit the file to change what the model sees as that tool's description. Placeholders (${os}, ${shell}, ${directory}, etc.) are preserved from the original descriptions.

Drift Detection

When OpenCode adds new built-in tools or changes tool IDs, the shipped tool/*.txt files may fall out of sync. Use the companion CLI script:

slim-plugin-check       # check coverage
slim-plugin-check --diff  # show exact add/remove/publish commands

The script lives at ~/.local/bin/slim-plugin-check (not shipped with this npm package).

Self-Update Notification

At startup, the server plugin fetches https://registry.npmjs.org/opencode-slim-system and compares dist-tags.latest against the installed version. If a newer version exists:

1. update_available: true and latest_version are written to the status file
2. The TUI sidebar shows an ⬆ indicator next to the version number
3. A dialog appears on first TUI start per version (dismiss once, silenced until next release)

No polling — the npm check runs once at startup with a 5-second timeout.

Files on Disk

Installation

# Install the plugin
npm install -g opencode-slim-system

# Or add to opencode.jsonc

In ~/.config/opencode/opencode.jsonc:

{
  "plugin": ["opencode-slim-system"]
}

In ~/.opencode/tui.json and/or ~/.config/opencode/tui.json:

{
  "plugin": ["opencode-slim-system"]
}

Restart OpenCode. On first TUI load you'll see a toast confirming the plugin loaded.

Limitations

• slimmed count is shipped files, not runtime coverage — The sidebar shows all 17 shipped description files. Actual tools slimmed depends on your experimental flags (lsp, plan_exit, repo_clone, etc. are conditional). For users without those flags enabled, the real count is ~14-15. The TUI always shows the larger number.
• Drift detection requires external script — The plugin no longer attempts to track missing tool descriptions (too many false positives from plugin tools). Run slim-plugin-check --diff after an OpenCode update to see if new built-in tools need slim descriptions.
• System prompt replacement uses marker heuristics — The hook looks for strings like "best coding agent on the planet" to identify stock prompts. Custom prompts (agents with custom .md files) are not touched.
• npm cache is sticky — OpenCode never re-fetches a cached npm package. Clear ~/.cache/opencode/packages/opencode-slim-system@latest/ to force a fresh download.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    OpenCode Session                       │
│  ┌──────────────┐    ┌─────────────────────────────┐     │
│  │ System Prompt │◄───│ experimental.chat.system    │     │
│  │ Construction  │    │    .transform (fallback)    │     │
│  └──────────────┘    └───────────┬─────────────────┘     │
│                                  │ reads                  │
│  ┌──────────────┐    ┌──────────▼─────────────────┐     │
│  │ Tool Schema  │◄───│ tool.definition (per tool)  │     │
│  │ Construction │    └──────────┬─────────────────┘     │
│  └──────────────┘               │ reads                  │
│                                 │ tool/*.txt files       │
│  ┌──────────────┐               │                        │
│  │ TUI Sidebar  │◄──── polls /tmp/opencode-slim-system   │
│  │ (order 899)  │       .json every 5s                  │
│  └──────────────┘                                        │
└─────────────────────────────────────────────────────────┘

License

MIT