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.
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.
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).
Add the plugin name to the plugin array in opencode.json:
{
"plugin": ["@bubblebuffer/opencode-workspaces"]
}OpenCode installs plugin dependencies at startup. No manual steps.
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.
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.
Returns all active workspaces for the project as { id, name, branch, directory }.
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.
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.
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.
- OpenCode with plugin support
- Node.js >= 18
- git >= 2.5
MIT