Conductor Setup

Configure a repository for Conductor — the macOS app for running parallel Claude Code workspaces.

Workflow

1. Detect project type

Inspect the repo to determine:

• Package manager: npm, pnpm, yarn, pip, mix, bundler, cargo
• Framework: Next.js, Django, Rails, Phoenix, etc.
• Dev server command: The command that starts the development server
• Env files: All .env and .env.local files (check root and subdirectories up to depth 2)
• Monorepo structure: Whether the dev server lives in a subdirectory (e.g., web/, apps/frontend/)

2. Create the setup script

Create scripts/conductor-setup.sh in the repo root:

#!/bin/zsh
set -e

echo "==> Conductor workspace setup"

symlink_env() {
  local src="$1"
  local dest="$2"
  if [ ! -f "$src" ]; then
    echo "  WARN: $src not found — skipping (add it via Repository Settings > Open In)"
    return 0
  fi
  ln -sf "$src" "$dest"
  echo "  OK: $dest -> $src"
}

echo "==> Symlinking .env files from CONDUCTOR_ROOT_PATH"
# Add one symlink_env call per .env file discovered:
symlink_env "$CONDUCTOR_ROOT_PATH/.env" ".env"
# symlink_env "$CONDUCTOR_ROOT_PATH/web/.env" "web/.env"        # monorepo example
# symlink_env "$CONDUCTOR_ROOT_PATH/.env.local" ".env.local"    # Next.js example

echo "==> Installing dependencies"
# Add the install command for the detected package manager:
# npm install              # npm
# pnpm install             # pnpm
# pip install -r requirements.txt  # python

echo "==> Conductor workspace ready"

Make it executable: chmod +x scripts/conductor-setup.sh

Customize the symlink calls and install command for the specific project.

3. Create conductor.json

Create conductor.json at the repo root:

{
  "scripts": {
    "setup": "zsh scripts/conductor-setup.sh",
    "run": "<dev-server-command> --port $CONDUCTOR_PORT",
    "archive": ""
  },
  "runScriptMode": "nonconcurrent"
}

Run command patterns by framework:

• Next.js (root): "npm run dev -- --port $CONDUCTOR_PORT"
• Next.js (monorepo): "npm --prefix web run dev -- --port $CONDUCTOR_PORT"
• Django: "python manage.py runserver 0.0.0.0:$CONDUCTOR_PORT"
• Rails: "bin/rails server -p $CONDUCTOR_PORT"
• Phoenix: "mix phx.server" (reads PORT env automatically)
• Python http: "python3 -m http.server --port $CONDUCTOR_PORT"
• Vite: "npx vite --port $CONDUCTOR_PORT"

Use nonconcurrent for dev servers (kills previous before starting new).

4. Symlink into existing workspaces

If the repo already has active Conductor workspaces, symlink .env files into them:

SRC="<repo-root-path>"
for ws in $(ls ~/conductor/workspaces/<repo-name>/); do
  WS_DIR="$HOME/conductor/workspaces/<repo-name>/$ws"
  ln -sf "$SRC/.env" "$WS_DIR/.env"
  # repeat for each .env file
done

5. Verify

Confirm the setup script symlinks are not broken and conductor.json is valid JSON.

Environment Variables

Reference

For full Conductor docs (conductor.json schema, run script modes, workspace locations), see references/conductor-reference.md.