[FEATURE]: \--worktree\ / \-w\ CLI flag for git worktree isolation

[atpaawej]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before (this is distinct from [FEATURE]: Configurable worktree creation — base ref, branch naming, repo-relative path #33332 and [FEATURE]: configurable path for worktrees #14032 — see "Related Issues" below).

Summary

OpenCode already has a mature worktree system — a full Worktree module, Desktop workspace UI, TUI slash commands via plugins, HTTP API endpoints, and .worktreeinclude support. However, it lacks a --worktree CLI flag that would let users start an isolated worktree session directly from the command line, similar to Claude Code's -w / --worktree flag.

Motivation

A --worktree CLI flag would enable:

1. One-shot isolated sessions: opencode --worktree fix-auth-bug — creates a worktree, opens a session inside it
2. PR workflow: opencode --worktree "#1234" — creates a worktree from a PR branch
3. CI/scripting: Non-interactive worktree creation for automation
4. Quick context switching: Spin up parallel isolated environments from the terminal without opening the Desktop app

Proposed Behavior

Based on the existing spec (commit 55b19fe on a fork) and Claude Code's model:

opencode --worktree <name>        # create with custom name
opencode --worktree "#1234"       # PR mode — create from PR
opencode --worktree               # auto-generate random name

Suggested defaults:

• Storage location: .opencode/worktrees/<name>/ (repo-local) or keep existing ~/.local/share/opencode/worktree/<project-id>/ (global)
• Branch naming: worktree-<name> or opencode/<name> (configurable?)
• Base ref: origin/HEAD (remote default) with optional config
• Session ID auto-bound to worktree name (mutually exclusive with --session)

Related Precedent

• The Desktop app already supports workspace (worktree) creation via right-click -> Enable Workspaces
• Community plugins exist for CLI-like workflows (DanHenton/opencode-worktree, sven1103/opencode-worktree-workflow, stephengolub/opencode-workspaces) — but none can add a true CLI flag due to plugin API limitations
• A detailed spec was drafted at obukhovaa/opencode commit 55b19fe but never merged
• .worktreeinclude support was added in PR feat(worktree): add .worktreeinclude support for copying gitignored files to new worktrees #25379 (May 2026)

Plugin Limitation

Plugins cannot register CLI flags — the yargs CLI is hardcoded. This must be implemented as a core PR in packages/opencode/src/cli/cmd/.

Existing Infrastructure

The plumbing already exists:

• packages/opencode/src/worktree/index.ts — Worktree.create(), Worktree.remove(), Worktree.list(), Worktree.reset()
• packages/opencode/src/control-plane/adapters/worktree.ts — WorktreeAdapter implements the generic WorkspaceAdapter interface
• HTTP API: POST /worktree, GET /worktree, DELETE /worktree
• Desktop: full workspace management UI

The missing piece is just the CLI integration layer.

Related Issues

• [FEATURE]: Configurable worktree creation — base ref, branch naming, repo-relative path #33332 — Configurable worktree creation (base ref, branch naming, path). That issue is about making the existing worktree system configurable. This issue is about adding a new CLI flag --worktree to trigger worktree creation from the command line. They are complementary — if [FEATURE]: Configurable worktree creation — base ref, branch naming, repo-relative path #33332 is implemented, --worktree should respect those config settings.
• [FEATURE]: configurable path for worktrees #14032 — Configurable path for worktrees. Again complementary — the --worktree flag could respect whatever storage path is configured.

This issue is specifically about the CLI integration layer — the yargs flag parsing, session-to-worktree binding, and PR mode. The config knobs in #33332 and #14032 are prerequisites for a polished implementation but not the same request.

[github-actions]

This issue does not fully meet our contributing guidelines.

What needs to be fixed:

• The title should start with [FEATURE]: to match the feature request template (e.g., [FEATURE]: --worktree / -w CLI flag for git worktree isolation)
• The feature request template requires a verification checkbox confirming the feature has not been suggested before

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Configurable worktree creation — base ref, branch naming, repo-relative path #33332: Configurable worktree creation (base ref, branch naming, repo-relative path) — overlaps significantly with the proposed --worktree CLI flag behavior including storage location, base ref, and branch naming options
• [FEATURE]: configurable path for worktrees #14032: Configurable path for worktrees — covers the storage location aspect of this request

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Thanks for updating the issue! It now meets our contributing guidelines. We'll take a look at your feature request.