TUI for managing git worktrees with opencode integration.
npm install opencode-worktreeTerminal UI for managing git worktrees and launching your preferred coding tool in the selected worktree.
- Lists all worktrees with branch, path, and metadata
- Worktree metadata display: last edited time, dirty status, remote tracking
- Status indicators: [main] for main worktree, [*] for uncommitted changes, [local] for local-only branches
- Create new worktrees directly from the TUI
- Create branch from worktree: create a new branch from any worktree's current commit, with optional checkout
- Post-create hooks: automatically run commands (e.g., npm install) after creating a worktree
- Open worktree folder in file manager or custom editor
- Unlink worktrees (remove directory, keep branch)
- Delete worktrees and local branches (never remote)
- Multi-select delete mode for batch deletion
- Customizable launch command: use opencode, cursor, claude, code, or any CLI tool
- Global configuration: settings stored in ~/.config/opencode-worktree/config.json with per-repo overrides
- Refresh list on demand
- Update notifications when new versions are available
- Git
- A CLI tool available on your PATH (e.g., opencode, cursor, claude, code)
``bash`
npm i -g opencode-worktree
`bash`
opencode-worktree
Or specify a repo path:
`bash`
opencode-worktree /path/to/your/repo
- Up/Down or j/k: navigateEnter
- : open selected worktree in configured tool (or toggle selection in delete mode)o
- : open worktree folder in file manager or custom editor (configurable)d
- : enter multi-select delete mode (press again to confirm deletion)n
- : create new worktreeb
- : create a new branch from selected worktree's current commitc
- : edit configuration (hooks, open command, launch command)r
- : refresh listq
- or Esc: quit (or cancel dialogs/modes)
1. Select a worktree and press b
2. Enter a name for the new branch
3. The branch is created starting from the worktree's current commit
4. Choose whether to checkout the new branch in the worktree
1. Press d to enter selection modeEnter
2. Navigate with arrow keys and press to toggle worktrees for deletiond
3. Press again to confirm and choose unlink/delete actionEsc
4. Press to cancel and return to normal mode
Configuration is stored globally at ~/.config/opencode-worktree/config.json with support for default settings and per-repository overrides. Press c in the TUI to edit settings.
Repositories are identified by their git remote URL (e.g., github.com/user/repo).
`json`
{
"default": {
"postCreateHook": "",
"openCommand": "",
"launchCommand": "opencode"
},
"repos": {
"github.com/user/repo": {
"postCreateHook": "npm install",
"launchCommand": "cursor"
}
}
}
| Option | Description | Default |
|--------|-------------|---------|
| postCreateHook | Command to run after creating a worktree | none |openCommand
| | Command for opening worktree folders (o key) | system default |launchCommand
| | Command to launch when selecting a worktree (Enter key) | opencode |
When you edit config in the TUI, settings are saved under the repo's key (derived from git remote URL):
`json`
{
"default": {
"launchCommand": "opencode"
},
"repos": {
"github.com/myorg/frontend": {
"postCreateHook": "npm install",
"openCommand": "code",
"launchCommand": "cursor"
},
"github.com/myorg/backend": {
"postCreateHook": "go mod download",
"launchCommand": "zed"
}
}
}
Press c at any time to edit your configuration. The config editor title shows which repository you're configuring (e.g., "Config: github.com/user/repo"). Use Tab to switch between fields.
Note: Repositories without a git remote will use default settings. The TUI shows a warning when editing config for repos without a remote.
Run a command automatically after creating a new worktree. Useful for installing dependencies.
The hook output is streamed to the TUI in real-time. If the hook fails, you can choose to open the tool anyway or cancel.
Examples: npm install, bun install, npm install && npm run setup
Use a custom command when pressing o to open worktree folders. Useful for opening in your preferred IDE.
Examples: code, webstorm, idea
Use a different tool instead of opencode when pressing Enter to open a worktree. This allows you to use any CLI-based coding tool.
Examples: cursor, claude, code, zed
Previous versions stored config in .opencode-worktree.json files in each repository. These files are now ignored. Your settings will need to be reconfigured via the TUI (c key), which will save them to the new global config location.
When a new version is published to npm, the TUI will show a non-intrusive update message in the title bar. The version check runs in the background and doesn't slow down startup.
`bash`
bun install
bun run dev
`bash`
bun run build:single
Build all platforms (release only):
`bash``
bun run build:all