Linear Worktree

linear-worktree

Delegate to the globally available linear-worktree CLI. Do not reimplement worktree, Linear, prompt, screenshot, or cmux logic inline.

Reference Files

Workflow

Copy this checklist to track progress:

linear-worktree progress:
- [ ] Confirm global CLI is available
- [ ] Choose mode
- [ ] Run the CLI
- [ ] Verify result or drive spawned sessions

1. Confirm install:

   command -v linear-worktree
   linear-worktree --help

2. Choose mode:

• One issue: linear-worktree ENG-423
• Many bare issue IDs: linear-worktree ENG-423 ENG-424
• Safe prompt/worktree only: linear-worktree --print ENG-423

3. Run from the intended repo, or pass --repo <path>. 4. In launch mode, the CLI creates the worktree, starts Claude with --dangerously-skip-permissions, and runs Claude from the new worktree directory.

Local Global Install

If the command is missing, install from the canonical repo:

cd ~/Code/mblode/linear-worktree
npm install
npm run build
npm link
command -v linear-worktree

Gotchas

• Launch cwd matters. Claude must start from the new worktree, not the repo that spawned the command.
• Multiple IDs fan out. Two or more bare issue IDs create cmux workspaces instead of doing all work in the current shell.
• Use `--print` for safe validation. It creates the worktree and prints the prompt without opening Claude.
• Repo comes from cwd or `--repo`. Run from inside the target repo, or pass --repo <path> when outside it.

Related Skills

• cmux / cmux-workspace for driving spawned workspaces.
• handoff when the Linear issue needs a richer brief than its description.

Drive Spawned Workspaces

After fan-out, use cmux tools to inspect and drive each workspace. Do not start duplicate sessions.

Inspect

cmux read-screen --workspace <workspace> --lines 40

Look for whether Claude is asking a question, presenting a plan, or ready for implementation.

Answer

cmux send --workspace <workspace> "answer text\n"
cmux send-key --workspace <workspace> down
cmux send-key --workspace <workspace> enter

Use free text for clarifying questions. Use key presses for selecting plan options when the UI presents a menu.

Ship

When a workspace has completed the requested implementation:

cmux send --workspace <workspace> "commit and open a PR\n"

Read the relevant ticket and local screenshots before answering questions for a spawned workspace.

Evaluation Scenarios

Use these scenarios when changing the skill or CLI.

Scenario 1: Single Issue

Query:

linear-worktree ENG-423

Expected behavior:

• Confirms linear-worktree is installed if needed
• Runs one-issue mode
• Creates a sibling worktree
• Launches Claude with --dangerously-skip-permissions
• Starts Claude from the worktree directory

Scenario 2: Safe Validation

Query:

test linear-worktree without launching Claude

Expected behavior:

• Uses linear-worktree --print <id>
• Verifies worktree and branch
• Does not use live cmux or Claude

Scenario 3: Multi-Issue Fan-out

Query:

spin up ENG-423 ENG-424 WEB-12

Expected behavior:

• Uses multi-ID mode
• Resolves repo per issue
• Creates one cmux workspace per issue
• Does not manually reimplement the worktree logic

Repo Detection

The CLI chooses a repo per issue. First match wins:

1. --repo <path> 2. Current git repo (the directory you run the command from)

If neither resolves, the CLI errors. Run it from inside the target repo, or pass --repo <path> when you're outside it.

Worktree Location

Worktrees are siblings of the resolved repo:

~/Code/acme/web      -> ~/Code/acme/web-eng-423
~/Code/acme/api       -> ~/Code/acme/api-web-12

Do not create nested worktrees inside the source repo.

Troubleshooting

Command Missing

cd ~/Code/mblode/linear-worktree
npm install
npm run build
npm link
command -v linear-worktree

command -v linear-worktree should resolve to the npm-linked TypeScript CLI, not /Users/mblode/dotfiles/bin/linear-worktree.

Repo Detection Fails

Run from inside the target repo or pass:

linear-worktree --repo ~/Code/acme/web ENG-423

Default Branch Fails

The source repo needs origin/HEAD:

git remote set-head origin --auto

cmux Fan-out Fails

Confirm both commands are reachable:

command -v cmux
cmux ping
command -v claude

Launch Fails

Use --print to validate worktree and prompt generation without launching:

linear-worktree --print ENG-423

Usage Modes

Use the smallest mode that matches the user's request.

One Issue

linear-worktree ENG-423

Creates a sibling worktree, changes launch cwd to that worktree, and starts:

claude --dangerously-skip-permissions "<prompt>"

The prompt is Linear's issue context plus local screenshot paths when LINEAR_API_KEY is set.

Many Issues

linear-worktree ENG-423 ENG-424 WEB-12

Every token must be a bare issue ID. The CLI creates one cmux workspace per issue. Each workspace runs linear-worktree <id>, so the worktree is created inside that workspace before Claude opens from the created worktree.

Print Only

linear-worktree --print ENG-423

Use this for validation, review, or handoff. It creates the worktree, prints the prompt, copies the cd command when clipboard tooling exists, and does not launch Claude.

ID Plus Slug

linear-worktree ENG-423 add launch mode

Treats the first token as the issue ID and the rest as the branch slug. This is single-issue mode, not fan-out.

Verification

Static Checks

Run from ~/Code/mblode/linear-worktree:

npm run build
npm run typecheck
npm run lint
npm run test

Global Install

npm link
command -v linear-worktree
linear-worktree --version
linear-worktree --help

Safe Behavior Check

In a temp or disposable git repo with origin/HEAD set:

linear-worktree --print TST-123

Confirm:

• sibling worktree exists
• branch is tst-123
• fallback prompt prints
• Claude does not launch

Live Checks

Only after static and safe checks pass:

• One real issue launch in a known-safe repo
• One small multi-ID fan-out with cmux reachable
• Read one spawned workspace and confirm Claude starts from the created worktree