Configure settings
Set personal defaults, project settings, and local project overrides in Conductor
Use this guide when you want to configure the settings most people edit directly: your global defaults, a project's shared settings, and your local overrides for one project.
Conductor's settings work like VS Code settings. User settings apply broadly, project settings apply to one repository, and local project settings override that repository on one machine. Organization-managed settings also exist, but most users do not need them.
Before you start
You need:
- A repository already added to Conductor.
- A terminal open at the repository root if you are configuring project settings.
- The commands your project uses to install dependencies and start the app.
Use the Settings screen when you want Conductor to write settings for you. Edit TOML files directly when you want a project setting to be reviewable, committed, or shared with other workspaces.
Choose the settings layer
Pick the file that matches who should receive the setting:
| If the setting should affect... | Edit this file |
|---|---|
| You, across all repositories | ~/.conductor/settings.toml |
| One repository or project | <repo>/.conductor/settings.toml |
| Only you, in one repository | <repo>/.conductor/settings.local.toml |
Repository local settings win over repository shared settings. Repository shared settings win over user settings.
If your organization manages Conductor settings, those values sit above the normal user and project stack. See Managed settings for that separate flow.
Configure your user defaults
Use user settings for personal defaults that should follow you across projects, such as model choices and reasoning defaults.
Create the user settings file
Create the settings directory if it does not exist:
mkdir -p ~/.conductorThen create or edit ~/.conductor/settings.toml:
"$schema" = "https://conductor.build/schemas/settings.schema.json"
[models]
default = "gpt-5.5"
review = "sonnet"
default_plan_mode = true
[models.codex]
default_thinking_level = "high"
personality = "direct"
[models.claude_code]
default_effort_level = "normal"Adjust the values
Keep only the defaults you actually want everywhere. For example, if you only want Codex sessions to start with higher reasoning, keep this smaller file:
"$schema" = "https://conductor.build/schemas/settings.schema.json"
[models.codex]
default_thinking_level = "high"Configure shared project settings
Use shared project settings for repository behavior that should travel with the project, such as setup scripts, run scripts, Files to copy patterns, prompts, environment variables, and Git behavior.
Create the project settings file
From the repository root, create the settings directory if it does not exist:
mkdir -p .conductorThen create or edit .conductor/settings.toml:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
setup = "pnpm install"
run = "pnpm dev --port $CONDUCTOR_PORT"
run_mode = "concurrent"Use your project's real setup and run commands. Use CONDUCTOR_PORT when the development server can accept a custom port, so multiple workspaces can run at the same time.
Choose the run mode
Keep run_mode = "concurrent" when each workspace can run independently.
Use run_mode = "nonconcurrent" when the project depends on one fixed port, one local database, one Docker stack, or another shared resource:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
setup = "pnpm install"
run = "pnpm dev"
run_mode = "nonconcurrent"Add project-specific details
Add sections only when the project needs them. For example, this project also copies gitignored environment files, sets an agent prompt, and customizes branch names:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
file_include_globs = ".env*\nconfig/*.local.json\n"
[scripts]
setup = "pnpm install"
run = "pnpm dev --port $CONDUCTOR_PORT"
run_mode = "concurrent"
[prompts]
general = "Prefer small, reviewable changes and run the narrowest relevant tests."
[git]
branch_prefix_type = "custom"
branch_prefix = "agent"Commit the shared settings
Commit .conductor/settings.toml when the settings should apply to the project:
git add .conductor/settings.toml
git commit -m "Add Conductor project settings"Configure a local project override
Use .conductor/settings.local.toml when your machine needs a different value from the shared project file.
Ignore the local override file
From the repository root, add the local settings file to .gitignore:
touch .gitignore
grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignoreAdd your local overrides
For example, override the Run button command and a local provider URL on your machine:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
[scripts]
run = "pnpm dev --host 127.0.0.1 --port $CONDUCTOR_PORT"
[environment_variables]
ANTHROPIC_BASE_URL = "http://127.0.0.1:4000"This file overrides matching values from .conductor/settings.toml only for your local checkout.
Verify the settings
Create a new workspace from the repository. Conductor should run the setup script from .conductor/settings.toml and use the shared Run button command unless your local override replaces it.
For a quick check, click Run in the workspace and confirm the command starts with the expected port behavior. If you configured CONDUCTOR_PORT, create a second workspace and confirm both workspaces can run at the same time.