Repository Settings

Relevant source files

The following files were used as context for generating this wiki page:

• crates/core/src/settings.rs
• crates/gtk-app/src/settings.rs
• crates/core/src/repository.rs
• README.md
• progress.md
• crates/gtk-app/src/main.rs
• crates/gtk-app/src/projects.rs

Repository Settings (often referred to as Project Settings) define the behavior, automation, and environmental configuration for a specific codebase within Linux Archductor. These settings allow developers to customize how coding agents interact with the repository, define scripts for setup and execution, and establish Git conventions such as branch naming and merge rules. Sources: README.md:213-219, crates/core/src/settings.rs:13-24

The system employs a layered configuration model, distinguishing between shared settings that are committed to version control and local overrides for machine-specific needs. This ensures that team-wide standards are maintained while allowing individual flexibility for local environments and secrets. Sources: README.md:213-222, crates/core/src/settings.rs:218-223

Configuration Architecture

The settings system is built on a hierarchy of TOML files located within the repository root. This structure supports both collaborative team environments and isolated local configurations.

Layered Configuration Model

Linux Archductor merges settings from multiple sources to determine the final active configuration:

1. Shared Settings (.archductor/settings.toml): Contains project-level defaults, scripts, and prompts intended to be shared across the team and committed to Git. Sources: README.md:213-219, crates/core/src/settings.rs:205-212
2. Local Overrides (.archductor/settings.local.toml): Used for machine-specific overrides, such as specific executable paths or local environment variables. This file is typically gitignored. Sources: README.md:221-222, crates/core/src/settings.rs:205-212
3. Prompt Packs: External TOML files containing specialized prompt instructions (e.g., for security-heavy or refactor-only workflows). Sources: crates/core/src/settings.rs:253-273, README.md:246-248

Core Data Structures

The configuration is represented internally by the RepositorySettings struct, which aggregates several specialized sub-structs:

Struct	Description
ScriptSettings	Defines commands for setup, run, test, lint, and build.
PromptSettings	Instructions for agents regarding PR creation, code review, and test fixing.
ProviderSettings	Executable paths for agent harnesses like Claude Code or Codex.
GitSettings	Controls branch prefixing and archive/merge behavior.
CustomizationSettings	Deep configuration for naming, automation, and view preferences.

Sources: crates/core/src/settings.rs:13-118

Settings Lifecycle and Data Flow

Settings are managed through a flow of loading, validation, and persistence, primarily handled by crates/core/src/settings.rs.

Initialization and Validation

When a repository is first added, the system runs a bootstrap process via ensure_repository_config. This ensures the .archductor directory exists and seeds it with default settings if missing. Sources: crates/core/src/settings.rs:282-315, crates/core/src/repository.rs:61-63

Validation is enforced during both loading and saving to ensure data integrity:

• Run Mode: Must be concurrent or nonconcurrent.
• Environment Keys: Must be valid alphanumeric/underscore identifiers.
• Paths: working_directory must be a safe relative path within the worktree.
• Tabs: default_visible_tab must match known workspace tabs (e.g., changes, checks, chat).

Sources: crates/core/src/settings.rs:491-580

Loading Sequence

The load_repository_settings function performs a strict loading sequence:

Customization Categories

The CustomizationSettings block provides fine-grained control over the Archductor experience.

Automation and Lifecycle

Controls triggers for automated workflows. Key fields include:

• auto_setup: Boolean to run the setup script immediately after workspace creation.
• auto_start_agent: Specifies which agent (e.g., "codex") starts automatically.
• required_local_files: A list of files (like .env) that must be present in a workspace.

Sources: crates/core/src/settings.rs:136-159, README.md:275-285

Naming and Git Style

Defines conventions for repository artifacts:

• branch_template: Template for generated branch names (e.g., {prefix}/{type}-{slug}).
• default_merge_method: Options include squash, merge, or rebase.
• pr_body_sections: Defines standard headers for pull request descriptions.

Sources: crates/core/src/settings.rs:125-134, README.md:263-273

View and UI Preferences

Repository-level UI defaults applied in the GTK application:

• theme: system, dark, or light.
• accent_color: blue, green, amber, or rose.
• keybindings: Supports vim presets or custom action=shortcut mappings.
• default_visible_tab: Sets the initial tab when opening a workspace.

Sources: crates/core/src/settings.rs:188-204, crates/gtk-app/src/main.rs:88-103

Technical Implementation Details

Atomic Writes and Safety

The system uses an atomic write pattern in atomic_write_no_symlink to prevent configuration corruption. It writes to a temporary UUID-named file, syncs to disk, and then renames the file to the target path. It explicitly rejects writing to symlinks to prevent unauthorized filesystem access. Sources: crates/core/src/settings.rs:895-920

GTK Settings Editor

The GTK app provides a dedicated Settings page (crates/gtk-app/src/settings.rs) with a "Rail" navigation system.

Prompt Management

Prompts are treated as first-class citizens. The PromptSettings struct contains 15 distinct prompt types, including code_review, create_pr, test_fixing, and refactor_style. These are exposed in the UI through specialized TextView editors with individual labeled sections. Sources: crates/core/src/settings.rs:43-61, crates/gtk-app/src/settings.rs:253-305

Summary

Repository Settings serve as the core configuration engine for Linux Archductor, bridging the gap between Git conventions and agent automation. By utilizing a layered TOML-based system, it maintains a balance between shared team standards and individual developer needs, ensuring a consistent and programmable environment across all parallel workspaces. Sources: README.md:213-219, progress.md:65-71