Automation & Scripts
Relevant source files
The following files were used as context for generating this wiki page:
The automation and scripting system in Linux Archductor provides a robust framework for managing the lifecycle of coding workspaces and the behavior of autonomous agents. It allows repositories to "bootstrap" themselves by defining standardized commands for setup, execution, and verification, while also enabling fine-grained control over agent interactions through editable prompts and automated triggers.
The system is primarily driven by configuration stored in .archductor/settings.toml and .archductor/settings.local.toml within the repository root. These settings allow teams to encode their conventions, ensuring that every workspace created—whether from a branch, GitHub issue, or prompt—is consistently prepared and ready for parallel coding tasks.
Sources: README.md:143-149, claude/CLAUDE.md:12-25, crates/core/src/settings.rs:360-375
Scripting Lifecycle and Environment
The core of the automation system revolves around the ScriptSettings and AutomationSettings structures. These define the commands that Archductor executes during various stages of a workspace's life.
Lifecycle Scripts
Archductor supports several key script types that manage the running environment within a workspace:
- Setup Script: Executed after workspace creation or when preparation is needed (e.g.,
pnpm install). - Run Script: Starts the repository runtime or local development server (e.g.,
pnpm dev). - Archive Script: Runs before a workspace is archived to perform custom cleanup.
- Check Scripts: Standardized commands for
test,lint,typecheck, andbuild.
Sources: crates/core/src/settings.rs:96-105, README.md:214-225
Runtime Environment Variables
When scripts or agent sessions are launched, they receive a rich set of context variables to ensure they operate correctly within the isolated Git worktree.
| Variable | Description |
|---|---|
ARCHDUCTOR_WORKSPACE_NAME | The unique name of the active workspace. |
ARCHDUCTOR_WORKSPACE_PATH | The absolute path to the Git worktree. |
ARCHDUCTOR_WORKING_DIRECTORY | The absolute path to the selected subdirectory (for monorepos). |
ARCHDUCTOR_PORT | A stable base port allocated to this specific workspace. |
ARCHDUCTOR_LINKED_DIRECTORIES | Newline-separated list of name=path for linked workspaces. |
Sources: README.md:280-295, progress.md:126-132
Automation Logic Flow
The following diagram illustrates how automation scripts are integrated into the workspace lifecycle:
The system can be configured to fully automate the transition from creation to a running agent environment.
Sources: README.md:230-245, crates/core/src/settings.rs:125-148
Repository Automation Settings
The AutomationSettings struct enables pre and post hooks for nearly every major action in the project.
| Field | Type | Description |
|---|---|---|
auto_setup | Option<bool> | Automatically run the setup script after creation. |
auto_start_agent | Option<String> | The preferred agent to launch (e.g., "codex"). |
required_local_files | Vec<String> | Checks for existence of files like .env before starting. |
pre_workspace_create | Option<String> | Command to run before worktree creation. |
post_merge | Option<String> | Command to run after a successful PR merge. |
Sources: crates/core/src/settings.rs:125-148, README.md:415-425
Prompt Automation
Prompts are treated as first-class automation assets because they guide agent behavior. Archductor uses a layered approach to prompts, merging "Prompt Packs" with repository-level overrides.
Prompt Types and Purposes
Repositories can automate agent guidance by defining specific instructions for different scenarios:
new_workspace: Guidance for planning a new task.code_review: Instructions for evaluating changes for correctness and style.test_fixing: Automated guidance for reproducing and fixing failing tests.refactor_style: Constraints for behavior-preserving structural changes.
Sources: crates/core/src/settings.rs:43-61, README.md:375-395
Prompt Pack Architecture
The system supports "Prompt Packs," which are reusable collections of instructions. This allows teams to switch between profiles like strict-review or fast-prototype.
The final prompt used by an agent is a result of the active pack merged with specific repository overrides.
Sources: crates/core/src/settings.rs:360-380, crates/core/src/settings.rs:400-415
UI and CLI Interaction
Automation features are exposed through both the GTK interface and the CLI for flexibility.
CLI Automation Examples
The CLI allows for direct execution and management of automated tasks:
# Start a workspace runtime
linux-archductor run <workspace-name>
# Check source readiness (gh, linear auth)
linux-archductor workspace source-preflight
# Export settings for automation elsewhere
linux-archductor repo settings <name> export --local
Sources: crates/cli/src/main.rs:720-740, README.md:520-560
GTK Settings Panel
The GTK application provides a panel-style editor for managing these automation rules, including a dedicated "Advanced" section for raw TOML customization when the standard fields are insufficient.
Sources: crates/gtk-app/src/settings.rs:90-110, progress.md:195-205
Summary
The Automation & Scripts system in Linux Archductor transforms a Git repository into a managed environment for coding agents. By defining setup/run scripts and structured lifecycle hooks, developers can ensure that parallel work streams remain isolated yet consistent. The integration of "Prompt Packs" further automates the cognitive overhead of directing agents, allowing for highly specific and repeatable autonomous workflows.