Conductor is joining MetaSkip to docs content
Conductor

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

LayerApplies toWhere to edit it
User settingsEvery repository on this MacSettings, under Personal and Agents & environment
Repository settingsOne repository on this MacSettings, under the repository's name in the sidebar
Managed settingsEvery 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:

  1. Managed settings.
  2. Repository settings.
  3. User settings.
  4. 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:

TabSettings
EnvironmentEnvironment variables and env files passed to agents, terminals, scripts, and actions. See Conductor environment variables.
GitBranch new workspaces from, Remote origin, Delete branch on archive, Archive on merge, and Set upstream on plain git push.
ScriptsSetup script and Archive script. See Project scripts.
ActionsCustom actions, Run mode, Use spotlight testing, and the prompt preferences for code review, PR creation, fixing errors, resolving conflicts, and branch renames.
MiscIcon, 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.toml becomes 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.toml with your .conductor/settings.local.toml and saves the result as that repository's settings. Values from .conductor/settings.local.toml win.
  • conductor.json fills 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.

On this page