Compaction Model

[!NOTE] Built and maintained by MAD Software.

How It Works

OpenCode V2 loads plugins from two places. Server plugins extend sessions, tools, and shell behavior through opencode.json. TUI plugins extend the terminal interface through cli.json. Each package is independent, so install only what you want.

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f6f8fa', 'primaryBorderColor': '#57606a', 'primaryTextColor': '#24292f', 'lineColor': '#57606a'}}}%%
flowchart LR
    S["Server plugins (opencode.json)"] --> A["goal · background-subagent · lint-feedback · direnv · compaction-model"]
    T["TUI plugins (cli.json)"] --> B["goal · chat-title · sidebar-resize · usage · subagent-sidebar · stats"]

Plugins

Each plugin README documents its behavior, setup, and limitations.

Deprecated

@madsoftwaredev/opencode-btw (/btw) is deprecated and no longer maintained. Remove it from your OpenCode plugins configuration. Its source remains available for reference.

[!WARNING] Upgrading from 0.1.0? Background subagent, subagent sidebar, lint feedback, and direnv dropped the local. prefix from their plugin IDs in 0.1.1. npm package names are unchanged, but update any config rules that reference the old IDs (local.direnv is now direnv, and so on).

What This Looks Like

Session Stats in the Footer

44.4 tok/s · 3 turns · 8 steps

The stats plugin appends live token speed and session-wide turn and step counts to the prompt footer. Enable or disable each stat in cli.json, or save overrides with /stats.

Background Subagents by Default

Install

Requires OpenCode V2. Install each package you want with opencode plugin add:

# Server plugins (opencode.json)
opencode plugin add @madsoftwaredev/opencode-background-subagent
opencode plugin add @madsoftwaredev/opencode-lint-feedback
opencode plugin add @madsoftwaredev/opencode-direnv
opencode plugin add @madsoftwaredev/opencode-compaction-model

# TUI plugins (cli.json)
opencode plugin add @madsoftwaredev/opencode-subagent-sidebar
opencode plugin add @madsoftwaredev/opencode-stats
opencode plugin add @madsoftwaredev/opencode-chat-title
opencode plugin add @madsoftwaredev/opencode-sidebar-resize
opencode plugin add @madsoftwaredev/opencode-usage

# Server + TUI
opencode plugin add @madsoftwaredev/opencode-goal

Restart the OpenCode TUI after installing a TUI plugin.

Stats and usage are separate: stats adds speed, turns, and steps to the footer; usage adds token and cost accounting to the sidebar and /usage popup. Install either or both. Goal needs its server plugin running for its TUI to show state.

Each package has its own version line, so opencode plugin update moves only the packages that changed.

opencode plugin list
opencode plugin check
opencode plugin update

Configure Compaction

The compaction plugin defaults to opencode-go/deepseek-v4.1-flash#max. To use a different connected model, set options.model in its entry in opencode.json. Replace the package's string entry with the object form below, preserving your other plugins:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    {
      "package": "@madsoftwaredev/opencode-compaction-model",
      "options": {
        "model": "provider/model#variant"
      }
    }
  ]
}

Use provider/model from a connected provider; #variant is optional. On failure, the plugin logs a diagnostic and lets OpenCode use its normal session model for compaction. See the full compaction guide for details and a working configuration example.

Requirements

Develop

Development and tests require Bun, Node.js 22+, and direnv:

git clone https://github.com/madsoftwaredev/opencode-plugins.git
cd opencode-plugins
bun install --frozen-lockfile
bun run check

bun run check runs the entrypoint build check and all package and release-script tests. The test command preloads the OpenTUI Solid JSX transform for rendered TUI tests. Tests use temporary projects and do not require a live OpenCode server.

To try a package directly from the latest source before a release:

opencode plugin add 'github:madsoftwaredev/opencode-plugins#main::path:packages/direnv'

Replace direnv with the package directory you want to try.

Issues and ideas are welcome in the GitHub issue tracker.

bun install
bun run check

bun scripts/publish.ts packages/goal --expected-version 0.1.0

bun run release:plan packages/stats --expected-version 0.1.3 --dry-run

git add packages/stats/package.json bun.lock
git commit -m "release: stats 0.1.3"
git tag 'stats@0.1.3'
git push origin main 'stats@0.1.3'

License

MIT