opencode-branch

Floating Branch panel for OpenCode — ask a quick aside question, poke at a file, or check history without derailing the main session.

Branch runs as its own isolated session with a deny-by-default tool allowlist. Optional main-session context (compact / full / none) can be injected at prompt time.

Install

opencode plugin -g opencode-branch

Or add to ~/.config/opencode/tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["opencode-branch"]
}

Restart OpenCode after installing.

Requires OpenCode >= 1.17 (tested on 1.18+) with TUI plugin support.

Usage

| Command / key | Action | |---------------|--------| | /branch | Toggle the Branch panel | | /branch-clear | Clear the branch conversation | | /branch-model | Change the branch model | | /branch-history | Browse saved branch sessions | | /branch-reload | Reload branch.jsonc | | /branch-context | Cycle main-context mode: Compact → Full → None | | Ctrl+Shift+B | Toggle panel (default keybind) | | Alt+C | Clear | | Alt+T | Toggle thinking blocks | | Alt+H | History | | Alt+D | Delete focused/selected history entry | | Ctrl+Shift+X | Cycle context mode (when panel is open) | | Esc | Stop generation; in history, go back one level |

On macOS, Option/Alt often does not reach the TUI (terminal compose). Prefer /branch slash commands, or configure your terminal so Option acts as Meta (e.g. iTerm2: Left Option = Esc+).

Model changes use /branch-model (no default keybind — Tab is left to the host TUI).

Configuration

Settings live in ~/.config/opencode/branch.jsonc (created on first load):

{
  "model": null,
  "systemPrompt": "You are a concise branch assistant. Answer directly. Use tools only when helpful.",
  "keybind": "ctrl+shift+b",
  "clearKeybind": "alt+c",
  "thinkToggleKeybind": "alt+t",
  "historyKeybind": "alt+h",
  "deleteKeybind": "alt+d",
  "modelKeybind": false,
  "allowedTools": ["glob", "grep", "list", "read", "websearch", "webfetch"],
  "width": 56,
  "tokenLimit": 45000,
  "position": "bottom-right",
  "think": {
    "defaultState": "collapsed",
    "showSummary": false
  },
  "mainContext": {
    "defaultMode": "compact",
    "compactMaxChars": 50000,
    "fullMaxChars": 200000,
    "compactHeadMessages": 4,
    "compactTailMessages": 20,
    "fullIncludeToolOutputs": true,
    "contextKeybind": "ctrl+shift+x"
  }
}

Set any keybind to false or "none" to disable it.

Main-session context

Branch always uses its own session. When context mode is compact or full, the active main-session transcript is appended into the branch system prompt at submit time (not streamed into the main agent).

• compact (default): head + tail messages, tool summaries, character budget
• full: ordered transcript with tool details (optional raw outputs)
• none: no main-session context

The header chip main: compact|full|none shows the current mode (click or Ctrl+Shift+X / /branch-context to cycle).

History

Closing or clearing the panel saves the branch session under ~/.local/share/opencode-branch/history.json (50-entry FIFO). Browse with /branch-history or Alt+H.

In history: Esc / header Back pops one level (detail → list → chat). Up/Down move the list cursor; Enter opens detail; Delete acts on the focused or open entry.

Security

Tools are deny-by-default. Only IDs listed in allowedTools are granted. Full context mode can include main-session tool outputs — use fullIncludeToolOutputs: false or Context: None when that is sensitive.

Troubleshooting

• /branch missing: confirm opencode-branch is in tui.json (not only opencode.json), then restart. This package ships a prebuilt dist/tui.js TUI entry — required for OpenCode 1.18+ npm plugin loading.
• Alt keybinds do nothing on macOS: expected without Option-as-Meta; use /branch slash commands.
• Stale plugin after upgrade: opencode plugin -g -f opencode-branch then restart.

Development

bun install
bun run build
bun run typecheck
bun run test

Point tui.json at a local checkout for iteration:

{
  "plugin": ["file:///absolute/path/to/opencode-branch"]
}

License

MIT — see LICENSE.