Scripts

Conductor can prepare, run, test, and clean up projects from each workspace.

Conductor supports three repository scripts:

1. Setup script: runs when Conductor creates a workspace.
2. Run script: runs when you click the Run button.
3. Archive script: runs before Conductor archives a workspace.

Conductor also supports Spotlight testing for projects that cannot run cleanly from a workspace directory. Spotlight testing syncs one workspace back to the repository root so you can use the root directory's existing terminal, build cache, or local resources.

Configure personal scripts in Repository Settings. To share scripts with teammates, commit a conductor.json file.

For step-by-step guides, see:

• Setup script reference
• Files to copy
• Run script reference
• Shell configuration
• Use Spotlight testing
• Share scripts with teammates

Setup script

The setup script runs inside the newly created workspace directory.

Use it for files or commands that are not covered by Git checkout:

• Install dependencies.
• Copy or symlink .env files.
• Build generated assets.
• Initialize local services needed by the workspace.

Example:

npm install
ln -s "$CONDUCTOR_ROOT_PATH/.env" .env

Files to copy

Before writing a setup script only to copy .env files or local config, consider Files to copy. Conductor can copy matching gitignored files from the main repo into each new workspace.

Use Files to copy for static local files. Use a setup script when the workspace needs commands, generated files, symlinks, or workspace-specific resources.

Run script

The run script launches your app, server, test watcher, or another long-running command from a workspace.

Example:

python3 -m http.server --port "$CONDUCTOR_PORT"

Use Conductor environment variables when scripts need workspace-specific paths or ports.

For shell setup details, see Shell configuration.

Run script mode

runScriptMode controls whether multiple run scripts can run at once.

Use nonconcurrent when your project depends on a single shared resource, such as one fixed port or one local database.

Spotlight testing

Spotlight testing is an alternative run workflow for projects that need to execute from the repository root. When Spotlight is on, Conductor copies tracked changes from one workspace back to the repository root and gives you a terminal there.

Use Spotlight testing when your project depends on root-directory paths, expensive build artifacts, a fixed port, or a single local database. For details, see Spotlight testing.

Archive script

The archive script runs before Conductor archives a workspace. Use it to clean up resources outside the workspace directory.

Example:

rm -rf "$HOME/Library/Application Support/com.conductor.app.dev.$CONDUCTOR_WORKSPACE_NAME"

Process shutdown

When Conductor stops a process, it sends SIGHUP, waits up to 200ms, then sends SIGKILL if the process is still running.

Troubleshooting

If a script fails, see Troubleshooting issues.