OpenCode mini session

An OpenCode TUI plugin that opens interactive temporary mini sessions for side questions, either with injected main-session context or as a fresh no-context thread.

The mini session runs as an overlay alongside the main session without blocking it, so you can ask side questions while the main thread continues working.

Press alt+b for the default mini mode, or alt+n for a fresh mini mode with no copied conversation context. You can also run /mini or /mini-fresh from the command palette during any OpenCode session. Type a question in the mini session dialog and send it. The plugin:

1. Gathers context from the current session (token-limited)
2. Creates a temporary isolated session with that context
3. Sends your question to the AI and streams the response
4. Lets you ask follow-up questions in the same mini session
5. Optionally injects the full mini-session transcript back into the main thread
6. Deletes the ephemeral session on close

Just install the plugin with the OpenCode plugin manager:

opencode plugin add opencode-mini-session

Add it to your OpenCode CLI config (~/.config/opencode/cli.json):

{
  "plugins": [
    "opencode-mini-session"
  ]
}

For OpenCode V1 (>=1.17.18 <2), install the v1 plugin line:

opencode plugin opencode-mini-session@1 -g

Or add it to your V1 TUI config (~/.config/opencode/tui.json):

{
  "plugin": [
    "opencode-mini-session@1"
  ]
}

Keep the @1 suffix to stay on v1. Plugin v1.1.4 fixes the update check that could delete the installed v1 plugin when a v2 release was available. Existing users should refresh their installation to receive the fix; exact pins to older versions must be updated explicitly.

For V1 configuration and troubleshooting, use the v1 README. The remaining instructions on this page are for OpenCode V2.

All options are optional. Defaults are shown below.

If you want to customize the plugin, your config should look something like this:

{
  "plugins": [
    {
      "package": "opencode-mini-session",
      "options": {
        "model": "anthropic/claude-sonnet-4.6",
        "variant": "high",
        "tokenLimit": 10000,
        "keybind": "alt+m",
        "freshKeybind": "alt+f",
        "enableThinking": true,
        "toggleThinkingKeybind": "alt+a",
        "agent": "build"
      }
    }
  ]
}

If agent is not set or is invalid, mini uses a plugin managed custom mini agent with read only permissions: read, glob, grep, and webfetch.

To customize permissions, tone, instructions, or other behavior, set agent to an existing OpenCode agent name. The plugin will use that agent's settings directly.

See the OpenCode agent docs for more info on custom agent setup.

For example, configure mini to use a custom pirate agent:

{
  "plugins": [
    {
      "package": "opencode-mini-session",
      "options": { "agent": "pirate" }
    }
  ]
}

The mini session receives the main session's conversation as plain text:

• User questions
• Assistant responses
• Tool calls summarized inline (name + up to 4 input params, e.g. [tool: read path=src/foo.ts])

Oldest messages are dropped to fit the tokenLimit, and the result is injected into the system prompt inside <session-context> tags.

Fresh mini mode skips this copied-context step entirely.

If /mini is missing or the TUI does not load after updating OpenCode, close OpenCode and force a fresh plugin install:

opencode plugin remove opencode-mini-session
opencode plugin add opencode-mini-session
opencode

If refreshing the plugin does not work, close OpenCode, remove the cached npm package, then start OpenCode again.

Linux and macOS:

rm -rf ~/.cache/opencode/npm/opencode-mini-session@latest
opencode

Windows PowerShell:

Remove-Item -Recurse -Force "$HOME\.cache\opencode\npm\opencode-mini-session@latest"
opencode

For more information, see the official OpenCode docs for npm plugins and plugin cache and configuration locations.