Worktrees

Worktrees let you work on multiple branches of the same repo simultaneously. Each worktree is a separate directory with its own checkout, but they share the underlying .git database.

IsonForge integrates git worktree so you can launch a session in an isolated branch directory with one flag.

Create a worktree

isonforge -w feature-auth

This:

1. Resolves the repo root (git rev-parse --show-toplevel).
2. Creates <repo>/.isonforge/worktrees/feature-auth/ via git worktree add -b feature-auth.
3. chdirs into it.
4. Opens IsonForge in that directory.

The branch feature-auth is created off your current HEAD. Files there are independent of your main checkout - edit, commit, push without disturbing other work.

Auto-generated name

isonforge -w

If you don't pass a name, IsonForge generates wt-<timestamp-base36>. Useful for throwaway experiments.

Resume an existing worktree

isonforge -w feature-auth

Same command. If <repo>/.isonforge/worktrees/feature-auth/ already exists, IsonForge chdirs into it and resumes (without creating a new branch).

Start from a PR

isonforge -w pr-123 --from-pr 123

This:

1. Requires the gh CLI installed and authenticated (gh auth login).
2. Runs gh pr view 123 --json headRefName to resolve the PR's head branch.
3. Fetches the branch from origin.
4. Creates the worktree on that branch.

Now you're sitting in the PR's branch, in an isolated directory, ready to finish it:

isonforge -w pr-123 --from-pr 123 "finish what was left in this PR"

Also accepts PR URLs (https://github.com/org/repo/pull/123).

Layout

<repo>/
├── .git/                          # main repo + worktree metadata
├── src/                           # main checkout
├── .isonforge/
│   └── worktrees/
│       ├── feature-auth/          # branch: feature-auth
│       ├── pr-123/                # branch: <PR head>
│       └── wt-mz3a8q/             # branch: wt-mz3a8q

Worktrees are real git worktrees, manageable with standard tooling:

git worktree list
git worktree remove .isonforge/worktrees/feature-auth

Why worktrees instead of branch switching?

• No stash/unstash. Your in-progress work on main stays untouched while you experiment.
• Run tests in parallel. pnpm test in main, pnpm test in the worktree, simultaneously.
• Isolated build artifacts. node_modules, target/, dist/ are per-directory.
• Background agents per branch. Launch isonforge --bg from a worktree to keep an agent working on a feature while you do something else in main.

Cleanup

When done:

git worktree remove .isonforge/worktrees/feature-auth
git branch -d feature-auth   # if you don't need the branch

Or if you just want a stale worktree gone:

rm -rf .isonforge/worktrees/feature-auth
git worktree prune

With other flags

Combine with anything:

isonforge -w refactor \
  --permission-mode plan \
  --effort xhigh \
  "refactor the auth flow"

Or as a background agent:

isonforge -w nightly-audit --bg "audit every fetch call for missing await"

The worktree is created, then the agent runs inside it.

Caveats

• Initial worktree creation needs a clean working tree. Git refuses to create a worktree from dirty state. Commit or stash first.
• Shared node_modules won't work. Each worktree has its own. pnpm install per worktree, or use pnpm workspace settings.
• Worktree dir is gitignored from the parent. IsonForge writes to .isonforge/worktrees/ which should be in .gitignore. Add it:

# .gitignore .isonforge/worktrees/

• Branch must not be checked out elsewhere. If the branch is currently in your main checkout, switch off it first before creating a worktree for it.

When worktrees aren't the right fit

• Tiny edits. Overhead isn't worth it for a one-line fix.
• Shared global state. If your dev server, db, or cache is shared across worktrees, parallel work creates collisions.
• Heavy build artifacts. Multiple target/ directories chew disk.