Settings reference

The complete schema for .archductor/settings.toml and .archductor/settings.local.toml. For the opinionated version — what to set and why — read Project setup.

The schema accepts more keys than the daemon currently honors. Rather than hide that, every table below marks status. Acted on means the daemon uses it today. Accepted means it parses and round-trips cleanly but changes nothing yet.

Top level

Key	Type	Status	Notes
`$schema`	string	Acted on	Editor completion only
`file_include_globs`	multiline string	Acted on	Gitignored files to copy into a new worktree. Combined with `.worktreeinclude`, not overridden by it. No runtime default — `.env*` is only scaffolded into a new file
`env_file_refs`	multiline string	Acted on	Env files parsed and injected. Missing file = launch failure
`environment_variables`	table	Acted on	Injected on top of the built-ins
`spotlight_testing`	bool	Acted on	Default false. Enables `spotlight-start` / `spotlight-stop`
`enterprise_data_privacy`	bool	Accepted
`claude_code_executable_path`	string	Acted on	Top-level, not in a table
`codex_executable_path`	string	Acted on	Top-level, not in a table
`claude_provider`	string	Acted on	Used by the readiness probe
`bedrock_region`	string	Accepted
`vertex_project_id`	string	Accepted

`[scripts]`

Key	Type	Status	Notes
`setup`	string	Acted on	Runs once per new workspace
`run`	string or table	Acted on	Table form is `[scripts.run.<id>]` with `command`, `default`, `available_in`, `icon`
`archive`	string	Acted on
`test`	string	Acted on	Check key `test`
`lint`	string	Acted on	Check key `lint`
`typecheck`	string	Acted on	Check key `typecheck`
`build`	string	Acted on	Check key `build`
`run_mode`	string	Acted on	`concurrent` (default) or `nonconcurrent`

`[prompt_pack]` and `[prompts]`

Key	Type	Status	Notes
`prompt_pack.active`	string	Acted on	Pack name
`prompt_pack.path`	string	Acted on	Must be a file directly under `.archductor/prompt-packs/`
`prompt_pack.version`	string	Acted on
`prompts.*`	string	Acted on	Overrides the active pack key by key

Prompt keys: new_workspace, general, continue_work, summarize_session, handoff, code_review, create_pr, fix_errors, resolve_merge_conflicts, rename_branch, commit_generation, push_branch, merge_pr, revert_changes, review_comments, test_fixing, refactor_style, setup_script, run_script.

`[git]`

Key	Type	Status	Notes
`archive_on_merge`	bool	Acted on	Archive the workspace as part of a successful merge
`delete_branch_on_archive`	bool	Accepted	Editable in Settings, not yet enforced
`worktree_push_auto_setup_remote`	bool	Accepted
`branch_prefix`	string	Accepted	Use `customization.workspace_defaults.branch_prefix`
`branch_prefix_type`	string	Accepted

`[customization.naming]`

Key	Type	Status	Notes
`workspace_name_style`	string	Acted on	`city` (default) generates city names; any other value falls back to `workspace`, `workspace-1`, …
`default_merge_method`	string	Acted on	Used by `pr merge` when `--method` is omitted
`pr_title_template`	string	Acted on	Placeholders: `{workspace}`, `{branch}`, `{summary}`, `{session_summary}`, `{changed_files}`, `{changed_files_count}`, `{type}`
`pr_body_sections`	array	Acted on	Replaces the default Summary / What Changed / Why / User Impact / Validation headings
`branch_template`	string	Accepted
`commit_style`	string	Accepted

`[customization.automation]`

Key	Type	Status	Notes
`auto_setup`	bool	Acted on	Run the setup script automatically on workspace creation
`test_command`	string	Acted on	Fallback for `scripts.test`
`lint_command`	string	Acted on	Fallback for `scripts.lint`
`typecheck_command`	string	Acted on	Fallback for `scripts.typecheck`
`build_command`	string	Acted on	Fallback for `scripts.build`
`auto_start_agent`	string	Accepted
`required_local_files`	array	Accepted	Use `env_file_refs` for a hard requirement
`pre_clone`, `post_clone`	string	Accepted
`pre_workspace_create`, `post_workspace_create`	string	Accepted
`pre_setup`, `post_setup`	string	Accepted
`pre_pr_create`, `post_pr_create`	string	Accepted
`pre_merge`, `post_merge`	string	Accepted
`pre_archive`, `post_archive`	string	Accepted

The lifecycle hooks — everything from pre_clone to post_archive — parse cleanly but nothing runs them yet. Do not build a workflow that depends on them.

`[customization.merge_rules]`

Key	Type	Status	Default
`block_on_open_todos`	bool	Acted on	true
`block_on_open_comments`	bool	Acted on	true
`block_on_failed_checks`	bool	Acted on	false
`block_on_pending_checks`	bool	Acted on	false
`definition_of_done`	string	Accepted

`[customization.workspace_defaults]`

Key	Type	Status	Notes
`base_branch`	string	Acted on
`workspace_parent`	string	Acted on	Where worktrees are created
`branch_prefix`	string	Acted on	Default `lc`. Issue workspaces become `<prefix>/gh-issue-<n>`
`working_directory`	string	Acted on	Scripts and sessions start here instead of the worktree root
`port_block_size`	integer	Acted on	Default 10. Allocation starts at 42000
`default_visible_tab`	string	Acted on
`auto_open`	bool	Accepted
`checkpoint_timing`	string	Accepted

`[customization.view]`

Key	Type	Status	Notes
`default_layout_preset`	string	Acted on	`code`, `wide`, `review`, `watch`, or a custom preset id. Written by `archductor layout set-default`
`theme`, `accent_color`, `colors`, `density`		See note
`keybindings`	string	See note
`terminal_font`, `terminal_scrollback`		See note
`command_palette_presets`	array	See note	Entries are `Label=command`
`notification_rules`	array	See note
`sidebar_layout`, `diff_preference`, `transcript_display`, `dashboard_columns`, `settings_import_export`		Accepted

Core surfaces theme, accent, density, keybindings, terminal font and scrollback, command-palette presets, and notification rules as repository view defaults, but the Electron app reads its own per-machine preferences instead. Change them in Settings, not in the TOML file.

`[customization.agent_profiles.<name>]`

Key	Status
`agent`, `model`, `approval_mode`, `reasoning_mode`, `personality`, `mcp_servers`	Accepted — profile names are surfaced, but profiles do not yet drive session launches

Injected environment variables

Available to every script and agent process:

Variable	Value
`ARCHDUCTOR_WORKSPACE_NAME`	The workspace name
`ARCHDUCTOR_WORKSPACE_PATH`	Absolute path to the worktree
`ARCHDUCTOR_WORKING_DIRECTORY`	Where scripts actually run
`ARCHDUCTOR_ROOT_PATH`	Absolute path to the main repository checkout
`ARCHDUCTOR_DEFAULT_BRANCH`	The repository’s default branch
`ARCHDUCTOR_PORT`	Base of this workspace’s reserved port block
`ARCHDUCTOR_IS_LOCAL`	Always `1`

Client environment variables

Read by the CLI, the desktop app, and MCP clients:

Variable	Effect
`ARCHDUCTOR_ARCHCAR_REMOTE`	Daemon address to use, overriding the saved profile
`ARCHDUCTOR_ARCHCAR_TOKEN`	Token for a TCP daemon address
`ARCHDUCTOR_ARCHCAR_LISTEN`	Server side: bind a TCP listener. A bare port means loopback
`LINEAR_API_KEY`	Required for Linear-sourced workspaces

If a key marked Accepted matters to you, that is useful signal — open an issue on conductor-arch rather than working around it.

Get started

Guides

Reference

Settings reference

Top level

`[scripts]`

`[prompt_pack]` and `[prompts]`

`[git]`

`[customization.naming]`

`[customization.automation]`

`[customization.merge_rules]`

`[customization.workspace_defaults]`

`[customization.view]`

`[customization.agent_profiles.<name>]`

Injected environment variables

Client environment variables

​Top level

​[scripts]

​[prompt_pack] and [prompts]

​[git]

​[customization.naming]

​[customization.automation]

​[customization.merge_rules]

​[customization.workspace_defaults]

​[customization.view]

​[customization.agent_profiles.<name>]

​Injected environment variables

​Client environment variables

Top level

`[scripts]`

`[prompt_pack]` and `[prompts]`

`[git]`

`[customization.naming]`

`[customization.automation]`

`[customization.merge_rules]`

`[customization.workspace_defaults]`

`[customization.view]`

`[customization.agent_profiles.<name>]`

Injected environment variables

Client environment variables