Settings
Where Conductor stores settings, how user, repository, and managed settings combine, and what each repository can override
Settings control how Conductor prepares workspaces, runs agents, starts projects, and configures providers. You edit them in the app: open Settings from the File menu or the Settings button in the side nav. For a step-by-step flow, see Configure settings.
Conductor saves settings on your Mac. They aren't stored in files in your repository or home directory, and they aren't shared with teammates.
Settings layers
| Layer | Applies to | Where to edit it |
|---|---|---|
| User settings | Every repository on this Mac | Settings, under Personal and Agents & environment |
| Repository settings | One repository on this Mac | Settings, under the repository's name in the sidebar |
| Managed settings | Every repository, overriding the other layers | ~/.conductor/settings.managed.toml, provided by your organization |
When more than one layer sets the same value, Conductor uses the first one in this order:
- Managed settings.
- Repository settings.
- User settings.
- Built-in defaults.
Most people don't have managed settings. See Managed settings if your organization uses them.
Repository settings
Select a repository in the Settings sidebar to see its tabs:
| Tab | Settings |
|---|---|
| Environment | Environment variables and env files passed to agents, terminals, scripts, and actions. See Conductor environment variables. |
| Git | Branch new workspaces from, Remote origin, Delete branch on archive, Archive on merge, and Set upstream on plain git push. |
| Scripts | Setup script and Archive script. See Project scripts. |
| Actions | Custom actions, Run mode, Use spotlight testing, and the prompt preferences for code review, PR creation, fixing errors, resolving conflicts, and branch renames. |
| Misc | Icon, Root path, Workspaces path, Preview URLs, Files to copy, and Enterprise data privacy. |
Environment and Git also exist as user settings. A repository value overrides the user value for that repository; other repositories keep the user value. Scripts, actions, run mode, and prompt preferences are repository settings only. Model defaults, reasoning defaults, and tool approvals are user settings only.
In a local workspace, an agent can read and change the repository's setup script, archive script, run mode, and actions for you. For example, use the prompt in Configure your project.
Settings files
Earlier versions of Conductor read settings from ~/.conductor/settings.toml, <repo>/.conductor/settings.toml, <repo>/.conductor/settings.local.toml, and <repo>/conductor.json. When you update, Conductor imports them once:
~/.conductor/settings.tomlbecomes your user settings. Its scripts, actions, run mode, and prompts are copied into each repository that doesn't set its own.- For each repository, Conductor merges the committed
.conductor/settings.tomlwith your.conductor/settings.local.tomland saves the result as that repository's settings. Values from.conductor/settings.local.tomlwin. conductor.jsonfills in values the settings files don't set, but only in repositories that have no.conductor/settings.toml, locally or on the remote default branch.
After the import, Conductor doesn't read or change these files, so editing them has no effect. Change settings in the app instead.
Repository settings are no longer shared through committed files. Each teammate configures the repository in their own Conductor. To keep teammates in sync, commit your setup logic as a script and point each setup script at it, and commit .worktreeinclude for Files to copy patterns.
Cloud organizations configure each repository's setup script in organization settings. See Repository setup scripts.