opencode-workspaces

TUI workspace management for OpenCode — switch between git worktrees without leaving your terminal.

What it does

opencode-workspaces brings the desktop app's workspace sidebar to the OpenCode TUI. It lets you:

• View all your git worktrees from any TUI screen
• Create new sandboxes (git worktrees on new branches) without leaving the TUI
• Switch between workspaces in-session — sessions stay in the current tab
• Scope sessions to a workspace so tool calls run in the right directory
• Rename, reset, and delete sandbox workspaces with keyboard-driven dialogs
• Browse sessions across workspaces with a filterable picker

Installation

Add to ~/.config/opencode/tui.json:

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

Or with opencode plugin add:

opencode plugin add opencode-workspaces

Usage

Enable workspaces

Workspaces are opt-in. Press ctrl+p to open the command palette and search for "Enable workspaces", or type /ws in any prompt.

Slash commands

| Command | Alias | Action | |---------|-------|--------| | /ws | /workspace | Open workspace menu (sub-picker) | | /ws-new | /wsn | Create a new workspace | | /ws-switch | /wss | Switch to a different workspace | | /ws-session | /wsc | New session in current workspace | | /ws-sessions | /wsl | Browse sessions across workspaces | | /workspaces | /wsm | Full-screen workspace manager |

Keyboard shortcuts (in the workspace manager)

| Key | Action | |-----|--------| | j / ↓ | Select next workspace | | k / ↑ | Select previous workspace | | n | New workspace | | r | Rename selected workspace | | R | Reset selected workspace to default branch | | d | Delete selected workspace | | Esc | Go back to home |

Home screen

When workspaces are enabled, a dashboard appears below the prompt showing:

• A list of your workspaces with session counts and status indicators
• Clickable actions: + new, ⎇ switch, ≡ manage
• A badge showing the currently active workspace

Sidebar (in session view)

The sidebar shows all workspaces with session counts. The workspace that owns the current session is highlighted with a ▸ prefix.

Configuration

Workspaces uses persistent KV storage (namespaced under workspace_tui:):

| Key | Type | Description | |-----|------|-------------| | workspace_tui:enabled | boolean | Whether workspaces feature is active | | workspace_tui:current | string | Currently selected workspace ID | | workspace_tui:names | object | Custom display names per workspace ID |

Requirements

• OpenCode ≥ 1.0.0
• Git repository with worktree support

How workspace switching works

When you switch workspaces, sessions created in that workspace are automatically scoped to its directory. The backend routes all session tool calls (file reads, shell commands, etc.) through the workspace's git worktree. Sessions remember their workspace — you don't need to re-select after reopening.

For new sessions, if the current workspace is a sandbox, createSession passes workspaceID so the server auto-routes all operations through that worktree.

Development

git clone https://github.com/stephengolub/opencode-workspaces
cd opencode-workspaces
npm install
npm run lint      # type check
npm test          # run 82 tests
npm run build     # emit dist/

To use the local plugin in your TUI:

{
  "plugin": ["/path/to/opencode-workspaces/src/index.tsx"]
}

License

MIT © Stephen Golub