opencode-workspaces

Directory-level workspace isolation for OpenCode agents. Wraps git worktrees behind a small set of tools so agents don't interact with git worktree directly.

Problem

Agents struggle with git worktree lifecycle. Common failure modes: stale worktrees left on disk after sessions end, merge targeting the wrong base branch, abandoned metadata, and directory collisions during parallel dispatch.

Worktrees are the correct primitive for parallel agent work, but the raw git worktree CLI surface requires orchestration that LLMs get wrong.

What this does

Exposes five tools to OpenCode agents:

| Tool | Behavior | |---|---| | workspace_create | Creates a git worktree on a new branch (rejects duplicates) | | workspace_activate | Activates a workspace or returns to project root | | workspace_list | Returns active workspaces for the current project | | workspace_remove | Removes a worktree; optionally merges to base branch first | | workspace_clean | Batch cleanup by age or specific workspace ID |

Workspace names serve directly as IDs, branch names, and directory names. Duplicates are rejected at creation time with a clear error. The metadata file (~/.config/opencode/workspaces.json) acts as the global registry.

Workspaces are created under .opencode/workspaces/. Metadata is stored in ~/.config/opencode/workspaces.json (overridable via WORKSPACES_METADATA_PATH).

Installation

Add the plugin name to the plugin array in opencode.json:

{
  "plugin": ["@bubblebuffer/opencode-workspaces"]
}

OpenCode installs plugin dependencies at startup. No manual steps.

Tool details

workspace_create(name, base_branch)

Creates a new git worktree from base_branch on a new branch named name.

Throws Workspace already exists: <name> if a workspace with the same name is already active for this project.

Returns { id, name, directory }. The id is the workspace name.

workspace_activate(id)

Activates a workspace by id (same as the workspace name), returning { id, name, branch, directory, baseBranch }.

Pass "." as the id to return to the project root: { id: ".", directory: "<project>" }.

Throws if the workspace is not found.

workspace_list

Returns all active workspaces for the project as { id, name, branch, directory }.

workspace_remove(id, merge?)

Removes a workspace by id. When merge is true, checks out the base branch and merges the workspace branch before removing the worktree.

Throws if the workspace is not found.

workspace_clean(workspace_id?, older_than_days?, force?)

Removes one or more workspaces. Can target a single workspace by workspace_id or filter by older_than_days. Bulk operations require force: true.

Returns a summary: count of cleaned, skipped, and errored workspaces, plus per-workspace details.

Usage with SuperPawers

This plugin provides the backend for the using-workspaces and finishing-a-workspace skills in SuperPawers. Those skills handle workspace lifecycle decisions (when to create, when to merge, when to discard) so agents don't need to reason about it.

The plugin itself does not depend on SuperPawers and can be used independently.

Requirements

• OpenCode with plugin support
• Node.js >= 18
• git >= 2.5

License

MIT