---
name: conductor
description: Build, configure, and troubleshoot Conductor workspaces, project setup recommendations, repository scripts, conductor.json, managed settings, files to copy, MCP, agent controls, and review workflows. Use when helping someone set up or operate Conductor.
license: Proprietary
compatibility: Conductor is a macOS app for running Claude Code and Codex agents locally in isolated git worktree workspaces.
---

# Conductor

Use this skill when helping a user configure, operate, or troubleshoot Conductor.

Conductor is a macOS app for running multiple coding agents in parallel. Each workspace is a separate git worktree and branch tied to a repository. Conductor currently supports Claude Code and Codex as agent types.

## When to use

Use this skill for:

-   Creating and explaining Conductor workspaces, branches, git worktrees, and `.context`.
-   Recommending project setup for a repository.
-   Writing or reviewing `conductor.json`.
-   Configuring setup, run, and archive scripts.
-   Configuring Files to copy or `.worktreeinclude`.
-   Explaining app settings, repository settings, managed settings, model providers, and privacy controls.
-   Guiding users through plan mode, fast mode, reasoning controls, Codex personality, checkpoints, MCP, slash commands, todos, and instruction files.
-   Helping users review, test, open PRs, interpret checks, and merge work.
-   Troubleshooting shell behavior, script failures, nested workspaces, privacy behavior, or permissions.

Do not claim Windows or Linux support. Conductor is a Mac app.

## Core model

-   Conductor runs agents locally on the user's Mac unless the documented cloud workspace path is explicitly involved.
-   Each repository has a main root directory and can have many workspaces.
-   Each workspace is a separate git worktree on its own branch.
-   Agents run with the user's local permissions unless the user configures stricter controls.
-   The repo root can contain a checked-in `conductor.json` file for shared repository settings.
-   Users can also configure personal repository settings in the Conductor app.
-   Personal Repository Settings on the user's machine override `conductor.json`.
-   Conductor workspaces include a gitignored `.context` directory for shared agent context.

Relevant docs:

-   https://conductor.build/docs/concepts/workspaces-and-branches
-   https://conductor.build/docs/concepts/workflow
-   https://conductor.build/docs/concepts/parallel-agents

## Workspace workflow

When explaining or troubleshooting a workspace, identify:

-   The repository root.
-   The workspace path.
-   The workspace branch.
-   Whether the workspace is local or using the documented cloud workspace path.
-   Whether setup has run successfully.
-   Whether the Run button command works from the workspace directory.
-   Whether the project assumes it is running from the repository root.
-   Whether `.context` contains shared instructions or files the agent needs.

Use this model when helping users:

1. Add or select a repository.
2. Create a workspace.
3. Let Conductor create a git worktree and branch.
4. Run setup if configured.
5. Start a Claude Code or Codex session.
6. Use the Run button for the development server or normal local loop.
7. Review the diff, checks, PR state, and deployment status.
8. Merge or archive when finished.

## Repository configuration

`conductor.json` lives at the repository root. Commit it when teammates should share the configuration.

Personal Repository Settings on the user's machine override conductor.json. To use the shared file, clear personal script overrides.

Supported `conductor.json` fields:

-   `scripts.setup`: Command to run when Conductor creates a workspace.
-   `scripts.run`: Command to run when the user clicks the Run button.
-   `scripts.archive`: Command to run before Conductor archives a workspace.
-   `runScriptMode`: Controls whether more than one run script can run at the same time.
-   `enterpriseDataPrivacy`: Disables features that require external AI providers.

Example:

```json
{
    "scripts": {
        "setup": "pnpm install",
        "run": "pnpm dev",
        "archive": "./script/workspace-archive.sh"
    },
    "runScriptMode": "concurrent"
}
```

Docs:

-   https://conductor.build/docs/reference/conductor-json
-   https://conductor.build/docs/reference/scripts/share-with-teammates

## Project setup recommendations

Recommend a concrete Conductor configuration after investigating how the target project is actually developed locally. Distinguish documented facts from inferred recommendations.

Inspect:

-   Inspect README files, docs, onboarding guides, package manager manifests, lockfiles, Procfiles, Docker Compose files, Makefiles, scripts, env examples, and existing conductor.json or .worktreeinclude files.
-   Identify setup commands, dependency managers, generated files, required environment or config files, local services, databases, caches, fixed ports, and commands developers use for the normal development loop.
-   Check whether commands can run from an arbitrary git worktree workspace or whether the project assumes the original repository root.
-   Look for port flags or environment variables that can be wired to CONDUCTOR_PORT and nearby allocated ports.
-   When Slack or internal search is available and relevant, search for prior guidance about worktrees, multiple local instances, port conflicts, shared databases, Docker stacks, or known local development pitfalls.
-   Distinguish documented facts from inferred recommendations.

Recommend:

-   Use Files to copy or a committed .worktreeinclude for static gitignored files such as .env files, local config, certificates, or tool state that should be copied into every workspace.
-   Use scripts.setup for commands that install dependencies, generate files, create symlinks, initialize per-workspace resources, or otherwise prepare a newly created workspace.
-   Use scripts.run for the normal long-running development server, app, worker, watcher, or test loop that should start from the Run button.
-   Use CONDUCTOR_PORT for local servers whenever the project supports configurable ports, and use CONDUCTOR_PORT+1 through CONDUCTOR_PORT+9 for companion services when needed.
-   Use runScriptMode concurrent only when multiple workspaces can safely run at the same time with separate ports and no conflicting shared local resource.
-   Use runScriptMode nonconcurrent when the project depends on one fixed port, one local database, one Docker stack, or another shared resource that cannot be made workspace-specific.
-   Recommend Spotlight testing when the project must run from the repository root, relies on expensive root-local build artifacts, or should use one heavy local stack while agents work in separate workspaces.
-   Put required shell or toolchain setup directly in setup and run scripts when possible so scripts do not depend on interactive shell startup behavior.

Deliver:

-   Short summary of the project's local development workflow.
-   Relevant Slack or internal guidance findings, with links or short quotes when available.
-   Exact proposed conductor.json, .worktreeinclude, setup scripts, run scripts, and repository settings to add or modify.
-   Explanation of why each script, file, setting, and mode is needed.
-   Validation steps the user can run to confirm workspace setup and run behavior.
-   Known limitations, risks, manual steps, or cases where multiple workspaces cannot run simultaneously.

Docs:

-   https://conductor.build/docs/reference/scripts
-   https://conductor.build/docs/reference/scripts/setup
-   https://conductor.build/docs/reference/files-to-copy
-   https://conductor.build/docs/reference/scripts/run
-   https://conductor.build/docs/reference/scripts/spotlight-testing
-   https://conductor.build/docs/reference/shells
-   https://conductor.build/docs/reference/environment-variables
-   https://conductor.build/docs/reference/conductor-json

## Scripts

Setup, run, and archive scripts run from the workspace directory.

Script facts:

-   Setup, run, and archive scripts run from the workspace directory.
-   Conductor uses non-interactive shells for scripts.
-   Although Conductor captures the login shell environment, most commands including setup and run scripts use `zsh`.
-   Use Files to copy or .worktreeinclude before writing setup scripts only to copy static gitignored files.
-   Use `CONDUCTOR_ROOT_PATH` when a workspace script needs a file from the repository root.
-   Use `CONDUCTOR_PORT` when multiple workspaces need separate local server ports.
-   Conductor allocates ten ports to each workspace: `CONDUCTOR_PORT` through `CONDUCTOR_PORT+9`.
-   Use `nonconcurrent` run script mode when a project depends on a single fixed port, single local database, or another shared resource.
-   When a run script starts multiple processes, keep them in the same process group with a tool such as `concurrently` instead of backgrounding commands with &.
-   When Conductor stops a process, it sends `SIGHUP`, waits up to `200ms`, then sends `SIGKILL` if the process is still running.
-   Use Spotlight testing when a project cannot run cleanly from a workspace directory and needs to execute from the repository root.

Environment variables:

-   `CONDUCTOR_WORKSPACE_NAME`: Workspace name.
-   `CONDUCTOR_WORKSPACE_PATH`: Workspace path.
-   `CONDUCTOR_ROOT_PATH`: Path to the repository root directory.
-   `CONDUCTOR_DEFAULT_BRANCH`: Name of the default branch, usually main.
-   `CONDUCTOR_PORT`: First port in a range of 10 ports assigned to the workspace.
-   `CONDUCTOR_IS_LOCAL`: `1` when the script runs on the user's Mac, `0` in a cloud workspace. Branch on this in `scripts.setup` to run local-only steps (e.g. Homebrew or nvm) only locally: `if [ "$CONDUCTOR_IS_LOCAL" = "1" ]; then ...`.

Docs:

-   https://conductor.build/docs/reference/scripts
-   https://conductor.build/docs/reference/scripts/setup
-   https://conductor.build/docs/reference/scripts/run
-   https://conductor.build/docs/reference/scripts/spotlight-testing
-   https://conductor.build/docs/reference/shells
-   https://conductor.build/docs/reference/environment-variables

## Settings

Use settings guidance when users ask about app settings, repository settings, managed settings, model providers, or privacy controls.

Managed settings:

-   Path: `~/.conductor/settings.json`
-   Schema: https://conductor.build/schemas/settings.json
-   Status: Managed settings are provisional.
-   Behavior: Managed values override local database settings, disable matching controls in Settings, and are used when Conductor launches agents.

Managed setting fields:

-   `enterpriseDataPrivacy`: Enable enterprise data privacy.
-   `claudeExecutablePath`: Override the Claude Code executable path.
-   `defaultModel`: Set the default model. Supported values are defined by the JSON Schema.

Docs:

-   https://conductor.build/docs/reference/settings
-   https://conductor.build/docs/guides/providers
-   https://conductor.build/docs/reference/privacy
-   https://conductor.build/docs/reference/security-and-permissions
-   https://conductor.build/schemas/settings.json

## Agent behavior

Use the agent behavior docs when users ask how to control Claude Code or Codex sessions.

Cover only documented behavior. Do not invent unsupported model providers, settings, APIs, or controls.

Common areas:

-   Plan mode.
-   Fast mode.
-   Model reasoning controls.
-   Codex personality.
-   Checkpoints.
-   MCP.
-   Slash commands.
-   Todos.
-   Instruction files.

Docs:

-   https://conductor.build/docs/reference/agent-behavior
-   https://conductor.build/docs/concepts/agent-modes
-   https://conductor.build/docs/reference/checkpoints
-   https://conductor.build/docs/reference/mcp
-   https://conductor.build/docs/reference/slash-commands
-   https://conductor.build/docs/reference/todos

## Review and merge

When helping users review and merge agent work, focus on the path from local changes to merged code.

Explain:

-   How to inspect changes in the diff viewer.
-   How to run or interpret checks.
-   How pull request state relates to the workspace branch.
-   How review comments, CI status, and deployments affect merge readiness.
-   What the user should verify before merging.

Recommend a validation step that exercises the riskiest part of the change.

Docs:

-   https://conductor.build/docs/guides/review-and-merge
-   https://conductor.build/docs/reference/diff-viewer
-   https://conductor.build/docs/reference/checks

## Troubleshooting

Start by identifying whether the issue is about repository setup, workspace creation, scripts, shell behavior, permissions, privacy settings, nested workspaces, agent behavior, or review flow.

Common checks:

-   Confirm the user is on macOS.
-   Confirm the repository root has a git repository and expected remote setup.
-   Confirm the failing command works from the workspace directory.
-   Confirm setup and run scripts do not depend on interactive shell startup behavior.
-   Check whether missing files are gitignored files that should be copied with Files to copy or `.worktreeinclude`.
-   Check whether the project requires fixed ports, a single local database, or a shared Docker stack.
-   Check whether `runScriptMode` should be `nonconcurrent`.
-   Check whether the project should use Spotlight testing because it cannot run cleanly from a workspace directory.
-   Check whether managed settings in `~/.conductor/settings.json` override app settings.
-   Check privacy and permission behavior before assuming an agent or provider issue.

Docs:

-   https://conductor.build/docs/faq
-   https://conductor.build/docs/troubleshooting/issues
-   https://conductor.build/docs/reference/shells

## References

Core concepts:

-   https://conductor.build/docs/concepts/workspaces-and-branches
-   https://conductor.build/docs/concepts/workflow
-   https://conductor.build/docs/concepts/parallel-agents
-   https://conductor.build/docs/concepts/agent-modes

Repository setup:

-   https://conductor.build/docs/reference/conductor-json
-   https://conductor.build/docs/reference/scripts/share-with-teammates
-   https://conductor.build/docs/reference/scripts
-   https://conductor.build/docs/reference/scripts/setup
-   https://conductor.build/docs/reference/scripts/run
-   https://conductor.build/docs/reference/scripts/spotlight-testing
-   https://conductor.build/docs/reference/shells
-   https://conductor.build/docs/reference/environment-variables
-   https://conductor.build/docs/reference/files-to-copy

Settings and privacy:

-   https://conductor.build/docs/reference/settings
-   https://conductor.build/docs/guides/providers
-   https://conductor.build/docs/reference/privacy
-   https://conductor.build/docs/reference/security-and-permissions
-   https://conductor.build/schemas/settings.json

Agent controls:

-   https://conductor.build/docs/reference/agent-behavior
-   https://conductor.build/docs/concepts/agent-modes
-   https://conductor.build/docs/reference/checkpoints
-   https://conductor.build/docs/reference/mcp
-   https://conductor.build/docs/reference/slash-commands
-   https://conductor.build/docs/reference/todos

Review and troubleshooting:

-   https://conductor.build/docs/guides/review-and-merge
-   https://conductor.build/docs/reference/diff-viewer
-   https://conductor.build/docs/reference/checks
-   https://conductor.build/docs/faq
-   https://conductor.build/docs/troubleshooting/issues
-   https://conductor.build/docs/reference/shells