Worktree Setup

Worktree Setup

Generate the right config so AI agents start in their isolated worktrees / environments with the same setup as the main repo: dependencies installed, env files in place, tool configs copied over.

1. Unless the context already provides an answer, explicitly ask the user which tool the setup is for: Cursor, Codex, Conductor, or Claude Code.

2. Map out the project (web, native, Rust, Swift, etc.) and make judgement calls on the right setup/install, run/actions, and teardown/archive commands.

Not all projects use bun. Some use make, cargo, bun tauri dev, swift build, npm, pnpm, pip, etc. Read the README, package.json scripts, top-level Makefile, or Cargo.toml to figure it out.

What each tool reads

• Cursor: Local parallel-agent worktrees in .cursor/worktrees.json.
• Codex: Setup script + actions in .codex/environments/environment.toml.
• Conductor: Workspace setup in conductor.json.
• Claude Code: .worktreeinclude at the repo root (gitignored files to copy into each worktree) + .claude/settings.json SessionStart hook for install.

The shared pattern

Across Cursor, Codex, and Conductor, the setup script usually does the same 3 things:

1. Install dependencies - run appropriate commands by project type, like Bun, Tauri, make, cargo, swift, etc. Read the README, package.json, Makefile, Cargo.toml, or similar to figure out what's right.
2. Copy AI-tool config dirs - .agents, .claude, .codex, .cursor from the source repo into the new environment.
3. Copy env files - .env, .env.local, .env.development, etc.

CRITICAL: the setup script always lives project-scoped, not global.

Claude Code is the exception: it auto-copies tracked files into each worktree and uses a declarative include list (.worktreeinclude) for gitignored files plus a SessionStart hook for install — no imperative setup script. See its section below.

Reusable copy snippet

Replace $SOURCE and $DEST with the right env vars for the platform (see the table near the bottom):

for d in .agents .claude .codex .cursor; do
    [ -d "$SOURCE/$d" ] && mkdir -p "$DEST/$d" && rsync -a "$SOURCE/$d/." "$DEST/$d/"
done
[ -f "$SOURCE/{ENV_FILE}" ] && cp "$SOURCE/{ENV_FILE}" "$DEST/{ENV_FILE}" || true

Templates

Replace {INSTALL_CMD}, {RUN_CMD}, and {ENV_FILE} per project.

Cursor

Cursor exposes $ROOT_WORKTREE_PATH (the source repo root). Scripts run inside the new worktree, so the destination is just the current working directory.

For OS-specific setups, use setup-worktree-unix or setup-worktree-windows. setup-worktree is the cross-platform fallback.

{
    "setup-worktree": [
        "{INSTALL_CMD}",
        "for d in .agents .claude .codex .cursor; do [ -d \"$ROOT_WORKTREE_PATH/$d\" ] && mkdir -p \"$d\" && rsync -a \"$ROOT_WORKTREE_PATH/$d/.\" \"$d/\"; done",
        "[ -f \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" ] && cp \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" \"{ENV_FILE}\" || true"
    ]
}

Codex

The file is autogenerated by the Codex desktop app - don't hand-edit it lightly, but it's plain TOML and committed to git. Schema:

version = 1
name = "{PROJECT_NAME}"

[setup]
script = '''
#!/usr/bin/env bash
set -euo pipefail

{INSTALL_CMD}

# Sync config dirs from source tree into the worktree
for d in .agents .claude .codex .cursor; do
    if [ -d "$CODEX_SOURCE_TREE_PATH/$d" ]; then
        mkdir -p "$CODEX_WORKTREE_PATH/$d"
        rsync -a "$CODEX_SOURCE_TREE_PATH/$d/." "$CODEX_WORKTREE_PATH/$d/"
    fi
done

# Copy env file if present
if [ -f "$CODEX_SOURCE_TREE_PATH/{ENV_FILE}" ]; then
    cp "$CODEX_SOURCE_TREE_PATH/{ENV_FILE}" "$CODEX_WORKTREE_PATH/{ENV_FILE}"
fi
'''

[[actions]]
name = "Dev Server"
icon = "run"
command = "{RUN_CMD}"

[[actions]]
name = "Build"
icon = "build"
command = "{BUILD_CMD}"

The [setup] script runs at the start of every new worktree / task. The [[actions]] blocks each become a named shortcut in the Codex UI. Common icons: run, build, debug, logs, check, package.

Conductor

conductor.json lives at the repo root and gets shared with teammates so everyone gets the same workspace setup.

Fields:

Template:

{
    "scripts": {
        "setup": "{INSTALL_CMD}; for d in .agents .claude .codex .cursor; do [ -d \"$CONDUCTOR_ROOT_PATH/$d\" ] && mkdir -p \"$CONDUCTOR_WORKSPACE_PATH/$d\" && rsync -a \"$CONDUCTOR_ROOT_PATH/$d/.\" \"$CONDUCTOR_WORKSPACE_PATH/$d/\"; done; [ -f \"$CONDUCTOR_ROOT_PATH/{ENV_FILE}\" ] && cp \"$CONDUCTOR_ROOT_PATH/{ENV_FILE}\" \"$CONDUCTOR_WORKSPACE_PATH/{ENV_FILE}\"",
        "run": "{RUN_CMD}"
    }
}

Claude Code

Claude Code's worktree manager auto-copies all tracked files (including .claude/) into each new worktree, so no rsync of config dirs is needed. Only gitignored files need to be listed explicitly, and install runs through a session hook.

Three artifacts, all at the repo root:

.worktreeinclude — one line per gitignored file to copy into every new worktree:

{ENV_FILE}

.claude/settings.json — runs {INSTALL_CMD} on every new Claude session and every fresh worktree. matcher: "startup" skips --resume so it doesn't fire on session resumes:

{
    "hooks": {
        "SessionStart": [
            {
                "matcher": "startup",
                "hooks": [
                    {
                        "type": "command",
                        "command": "{INSTALL_CMD}",
                        "timeout": 120
                    }
                ]
            }
        ]
    }
}

timeout is in seconds. Bump it for projects with cold-build steps (Tauri, Rust, Swift cold builds can run several minutes).

.gitignore — under a # claude code runtime block so the runtime worktree directory and lock file aren't committed:

# claude code runtime
/.claude/scheduled_tasks.lock
/.claude/worktrees/

Environment variables by platform

• Cursor: $ROOT_WORKTREE_PATH / (cwd is the new worktree, no separate destination var)
• Codex: $CODEX_SOURCE_TREE_PATH / $CODEX_WORKTREE_PATH
• Conductor: $CONDUCTOR_ROOT_PATH / $CONDUCTOR_WORKSPACE_PATH
• Claude Code: none — declarative (.worktreeinclude) + session hook; no source/dest vars.

Vendors rename these. Always check the platform's docs before writing them.

Usage

CRITICAL: The user is a non-technical, non-engineer. Avoid technical jargon and help them set up the correct setup scripts for their setup.

1. Identify which environment the project needs (per the user's answer).
2. Detect project type and pick {INSTALL_CMD} / {RUN_CMD} / {ENV_FILE} from the table above (or read the README).
3. Generate the matching config file from Templates.
4. Offer to git commit for teams to have access to it too.
5. Offer to also generate the same for other agents that this skill supports.