Creating and explaining Conductor workspaces, branches, git worktrees, and .context.
Recommending project setup for a repository.
Writing or reviewing conductor.json.
Configuring setup, remote 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:

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:

Add or select a repository.
Create a workspace.
Let Conductor create a git worktree and branch.
Run setup if configured.
Start a Claude Code or Codex session.
Use the Run button for the development server or normal local loop.
Review the diff, checks, PR state, and deployment status.
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 override conductor.json. If the user expects the shared file to apply, ask them to clear personal script overrides.

Supported conductor.json fields:

scripts.setup: Command to run when Conductor creates a workspace.
scripts.remoteSetup: Command to use instead of scripts.setup for remote or cloud workspaces.
scripts.run: Command to run when the user clicks the Run button.
scripts.archive: Command to run before Conductor archives a workspace.
runScriptMode: "concurrent" or "nonconcurrent".
enterpriseDataPrivacy: Boolean that disables features requiring external AI providers.

Example:

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

Docs:

Project setup recommendations

When asked to recommend Conductor setup for a project, investigate the project first. Distinguish documented facts from inferred recommendations.

Inspect:

README files, docs, and onboarding guides.
Package manager manifests and lockfiles.
Procfiles, Docker Compose files, Makefiles, and scripts.
Environment examples and local config examples.
Existing conductor.json or .worktreeinclude files.
Local services, databases, caches, generated files, fixed ports, and normal development commands.
Whether commands work from an arbitrary git worktree workspace.
Whether the project assumes the original repository root.
Port flags or environment variables that can use CONDUCTOR_PORT.
Prior Slack or internal guidance when available and relevant, especially for worktrees, multiple local instances, port conflicts, shared databases, Docker stacks, and known local development pitfalls.

Recommend:

Files to copy or a committed .worktreeinclude for static gitignored files such as .env files, local config, certificates, or tool state.
scripts.setup for dependency installation, generated files, symlinks, per-workspace resources, or other workspace preparation.
scripts.run for the normal long-running development server, app, worker, watcher, or test loop.
CONDUCTOR_PORT for local servers when the project supports configurable ports.
CONDUCTOR_PORT+1 through CONDUCTOR_PORT+9 for companion services when needed.
runScriptMode: "concurrent" only when multiple workspaces can safely run at the same time with separate ports and no conflicting shared local resource.
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.
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.
Required shell or toolchain setup directly in setup and run scripts when possible, so scripts do not depend on interactive shell startup behavior.

Deliver:

A 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.
Why each script, file, setting, and mode is needed.
Validation steps the user can run.
Known limitations, risks, manual steps, or cases where multiple workspaces cannot run simultaneously.

Docs:

Scripts

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

Script facts:

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.

Docs:

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: Boolean. Enable enterprise data privacy.
claudeExecutablePath: String. Override the Claude Code executable path.
defaultModel: String. Set the default model. Supported values are defined by the JSON Schema.

Docs:

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:

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:

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:

References

Core concepts:

Repository setup:

Settings and privacy:

Agent controls:

Review and troubleshooting:

conductor

Conductor

When to use