The Setup Process

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, or Conductor.

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.

The shared pattern

Across all of them, 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.

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:

Field	Type	Description
scripts.setup	string	Command to run when setting up a new workspace.
scripts.run	string	Command to start the dev server.
scripts.archive	string	Command to run when archiving a workspace.
runScriptMode	"concurrent" | "nonconcurrent"	Whether to kill in-progress run scripts before starting a new one.

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}"
    }
}

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

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.