> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings reference

> Every key in .archductor/settings.toml, and which ones the daemon actually acts on.

The complete schema for `.archductor/settings.toml` and
`.archductor/settings.local.toml`. For the opinionated version — what to set and
why — read [Project setup](/archductor/project-setup).

<Info>
  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.
</Info>

## 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 | |

<Warning>
  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.
</Warning>

## `[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 | |

<Note>
  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.
</Note>

## `[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 |

<Tip>
  If a key marked **Accepted** matters to you, that is useful signal — open an
  issue on
  [conductor-arch](https://github.com/perceo-ai/conductor-arch/issues) rather
  than working around it.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.