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

Variable	Description
$CONDUCTOR_ROOT_PATH	Persistent repo root (where .env files live)
$CONDUCTOR_PORT	Unique port per workspace
$CONDUCTOR_WORKSPACE_NAME	Workspace identifier

Reference

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