worktree-spinoff

Worktree spin-off (Orca IDE)

Self-Evolving Skill: This skill improves through use. If instructions are wrong, Orca's CLI changed, or a workaround was needed: fix this file and the script immediately, don't defer. Only update for real, reproducible issues.

Use this when a task should continue in its own Orca worktree, with its own branch, sidebar entry and agent session, instead of in the current one. One command, scripts/orca-spinoff, does the whole spin-off and the clean removal. It follows Orca's bundled orca-cli guide (orca skills get orca-cli) and keeps to Orca's native model: worktrees, the built-in agent launcher, repos and projects, hosts, and paired runtimes. Everything here was observed on Orca 1.4.22x on Linux and macOS.

Assumptions

• Orca IDE manages the agents. You drive Claude Code (or another TUI agent Orca knows: codex, gemini, …) through Orca's CLI and GUI, locally and on other devices through paired runtimes.
• The toolchain comes from Nix. One Nix profile gives the same current bash, git, python3 and coreutils on macOS, Linux and BSD, so the same commands behave the same everywhere. The script also runs on stock macOS (/bin/bash 3.2, BSD userland) because it uses no GNU-only flags. It needs bash ≥ 3.2, git ≥ 2.20, python3 ≥ 3.9 and the Orca IDE CLI.
• The repository is registered in Orca on the target runtime (orca repo add --path <checkout>), and its remote is reachable from the machine where you run the script.

Use

SPIN=<this skill's directory>/scripts/orca-spinoff     # e.g. from the plugin cache
"$SPIN" create --name my-task --title "My task (issue #12)" \
  --handoff ./handoff.md --display "My task: readable name" \
  [--issue 12] [--comment "status"] [--link .venv] [--setup skip] [--dry-run]
"$SPIN" remove --name my-task [--delete-remote-branch] [--force] [--dry-run]

• --title: the prompt's first line. Orca labels the agent's row in the sidebar with it, so keep it short and specific.
• --handoff FILE: committed as docs/handoff/<file> (--handoff-dir) before the agent starts. The default prompt tells the agent to read it first; --prompt-file replaces the prompt body.
• --link PATH: symlinks a path of the main checkout into the worktree, for things that are not in git: .venv, node_modules, .env.
• --handoff and --prompt-file: relative paths are relative to your current directory, also inside a linked worktree.
• Base: with a handoff, the remote's default branch (or --base). Without a handoff or --base, the script omits --base-branch, so Orca uses the repo's default base, as Orca's orca-cli guide asks for independent top-level handoffs.
• --dry-run: for create and remove, runs every check (repo, remote, base, collisions, leftovers, unsaved work), prints the plan, and changes no branch or worktree. It may still git fetch.
• Output: stdout is one JSON line, {"worktree", "path", "branch", "terminal", "terminals", "setup_tabs", "prompt_seen"} (terminals is null if Orca could not list them); progress and warnings go to stderr. The handoff is complete when prompt_seen is true. Report the worktree and terminal to the user; do not wait for the new agent to finish.