opencode-branch-switcher

An OpenCode plugin for switching, listing, and deleting git branches with auto-stash and safety checks.

Install

From npm

Add to your opencode.json:

{
  "plugin": ["opencode-branch-switcher"]
}

As a local plugin

Copy src/ into your project:

.opencode/plugins/branch-switcher.ts

Or clone the repo and symlink:

git clone https://github.com/carlos-rodrigo/branch-switch-opencode.git
ln -s /path/to/branch-switch-opencode/src/index.ts .opencode/plugins/branch-switcher.ts

If using a local plugin with dependencies, add a .opencode/package.json:

{
  "dependencies": {
    "@opencode-ai/plugin": "^1.0.85"
  }
}

Usage

Slash Commands

/branch - Interactive branch picker. Lists branches grouped by recent, local, and remote. Presents them via the question tool for selection.

/branch

/branch <name> - Switch directly to a branch.

/branch main
/branch feature/new-dashboard

/branches - List all branches with full metadata (date, ahead/behind, last commit).

/branches

/branch-delete <name> - Delete a branch with safety checks.

/branch-delete feature-old

Natural Language

The plugin registers tools that the LLM can call, so you can also use natural language:

"switch to the main branch"
"show me all branches"
"delete the feature-old branch"
"what branch am I on?"

Tools

branch_list

List branches sorted by recent activity with metadata.

| Arg | Type | Default | Description | |-----|------|---------|-------------| | includeRemote | boolean | false | Include remote-only branches | | limit | number | all | Max branches to return |

branch_switch

Switch to a branch with safety checks and auto-stash.

| Arg | Type | Default | Description | |-----|------|---------|-------------| | branch | string | required | Branch name to switch to | | autoStashEnabled | boolean | true | Auto-stash uncommitted changes |

branch_delete

Delete a branch with guards.

| Arg | Type | Default | Description | |-----|------|---------|-------------| | branch | string | required | Branch name to delete | | force | boolean | false | Force delete unmerged branches |

Safety

The plugin checks for these conditions before switching:

• Dirty working tree - Auto-stashes uncommitted changes (including untracked files) with a structured message. Restores them when you return to the branch.
• In-progress rebase - Blocks the switch and tells you to finish or abort.
• In-progress merge - Same as rebase.
• In-progress cherry-pick - Same as rebase.
• Worktree lock - Blocks if the target branch is checked out in another worktree.
• Detached HEAD - Warns before switching away from detached HEAD state.
• Remote-only branches - Fetches from remote and auto-creates a tracking local branch.

Auto-Stash

When switching with uncommitted changes:

1. Plugin stashes changes with message: opencode-auto-stash: <from> -> <to>
2. Switches to the target branch
3. Checks if the target branch has a matching auto-stash entry
4. Restores the stash if found (warns on conflict without dropping the stash)

Development

git clone https://github.com/carlos-rodrigo/branch-switch-opencode.git
cd branch-switch-opencode
bun install
bun tsc --noEmit  # type check

License

MIT