User and project settings
Reference for Conductor user, project, and local project settings
User and project settings are the files most people manage directly. Use this reference when you need to choose a settings tier or understand precedence. For the complete key list, see Settings reference.
For a step-by-step setup flow, see Configure settings.
File locations
Most users work with these files:
| Scope | File | Use it for | Commit it? |
|---|---|---|---|
| User shared | ~/.conductor/settings.toml | Your defaults across all repositories | No |
| Repository shared | <repo>/.conductor/settings.toml | Project-specific setup for one repository | Yes |
| Project overrides | <repo>/.conductor/settings.local.toml | Your override for one project | No |
Organizations can also provide a managed settings file at ~/.conductor/settings.managed.toml. Managed settings override user and project settings. See Managed settings when you need organization-controlled configuration.
Precedence
When more than one settings layer configures the same setting, Conductor uses the first matching value in this order:
- Managed settings.
- Project overrides.
- Repository shared settings.
- User shared settings.
- Built-in defaults.
Most users will not have managed settings. When no managed file is present, project overrides are the highest layer.
Example:
[scripts]
run = "pnpm dev"[scripts]
run = "pnpm dev --port $CONDUCTOR_PORT"For that repository, the Run button uses pnpm dev --port $CONDUCTOR_PORT because the repository shared file overrides the user shared file for repository-configurable settings.
If your local file also defines the run script, it wins for your machine:
[scripts]
run = "pnpm dev:local"Repository shared settings
Use <repo>/.conductor/settings.toml when a repository should define its own Conductor behavior. Commit this file when the settings should travel with the project.
Common repository shared settings include setup scripts, run scripts, archive scripts, run mode, Files to copy patterns, Enterprise data privacy, action prompts, Git behavior, provider executable paths, and repository environment variables.
Example:
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"
enterprise_data_privacy = true
[scripts]
setup = "pnpm install"
run = "pnpm dev --port $CONDUCTOR_PORT"
archive = "./script/workspace-archive.sh"
run_mode = "concurrent"
[prompts]
general = "Prefer small, reviewable changes and run the narrowest relevant tests."
code_review = "Focus on correctness, behavior changes, and missing tests."Use run_mode = "nonconcurrent" when the project depends on one fixed port, one local database, one Docker stack, or another shared resource that multiple workspaces cannot use at the same time.
Project overrides
Use <repo>/.conductor/settings.local.toml for settings that should apply only on your machine. Add it to .gitignore from the repository root:
touch .gitignore
grep -qxF ".conductor/settings.local.toml" .gitignore || printf "\n.conductor/settings.local.toml\n" >> .gitignoreProject overrides are useful when your local environment differs from the project's shared setup.
Example:
"$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 overrides the shared repository run script and environment variable values on your machine only.
User settings
Use ~/.conductor/settings.toml for personal defaults that should apply across repositories. User settings include every file-backed setting, including settings that repositories cannot control.
Example:
"$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"Common user-only settings include model defaults, model reasoning defaults, tool approvals, and the default workspace location. If you put these settings in a repository file, Conductor ignores them because repositories are not allowed to set them.
Schemas and legacy files
Add a schema URL to a settings file for editor autocomplete and validation. Schema URLs are listed in Settings reference.
Within one scope, Conductor reads legacy .json settings files first and .toml settings files second. If both exist, TOML wins. Conductor writes new settings files as TOML.
Legacy conductor.json is separate from these settings files. New shared repository settings should use .conductor/settings.toml. For migration details, see conductor.json.