Terminology & Concepts
Relevant source files
The following files were used as context for generating this wiki page:
Linux Archductor is a desktop control plane designed to manage parallel coding agents within isolated environments. The system orchestrates multiple workflows across a single codebase by leveraging Git worktrees to create distinct, task-specific environments where AI agents and developers can interact synchronously or asynchronously.
The project architecture follows a strict hierarchy where high-level "Projects" own repository configurations, while "Workspaces" serve as the primary units of work, each mapping to unique Git branches and disk paths. This model allows for complex operations—such as multi-agent sessions, pull request management, and conflict detection—to occur simultaneously without cross-contamination between tasks.
Sources: README.md:3-9, claude/CLAUDE.md:9-15
Core Product Hierarchy
The Archductor model organizes development work into a structural hierarchy. This ensures that repository-wide configurations (like scripts and prompts) are inherited by individual tasks while maintaining strict file-system isolation.
Structural Components
| Term | Definition | Relationship |
|---|---|---|
| Project | The top-level entry for a codebase. Owns settings, scripts, and instructions. | 1 Project contains 1 Repository |
| Repository | The underlying Git codebase, linked via local path or remote URL. | 1 Repository contains many Workspaces |
| Workspace | An isolated environment for a specific task, issue, or PR. | 1 Workspace maps to 1 Branch |
| Branch | The Git branch active in a workspace; the primary unit for PRs and reviews. | 1 Branch has 1 Working Tree |
| Working Tree | The actual files on disk for a workspace, created via Git worktrees. | 1 Working Tree belongs to 1 Workspace |
| Running Environment | The collection of active processes (terminals, agents, servers) in a workspace. | 1 Workspace runs many Processes |
Sources: README.md:14-25, claude/CLAUDE.md:20-31
Relationship Model
The following diagram illustrates the ownership and cardinality between core Archductor entities:
This diagram shows how a single project encapsulates the entire lifecycle of multiple parallel workstreams.
Sources: claude/CLAUDE.md:33-39, README.md:14-25
Workspace Environments & Sessions
A workspace is more than just a folder; it represents a "Running Environment" that encapsulates all activity related to a task.
Sessions
Sessions are PTY-backed (Pseudo-Terminal) harnesses that run interactive tools. Archductor supports several session types:
- Shell: Standard terminal access within the workspace path.
- Codex: AI agent sessions (OpenAI Codex) featuring structured transcript events.
- Claude: AI agent sessions (Claude Code) for parallel development.
- Cursor: Editor-specific sessions launched with workspace context.
Sources: progress.md:39-44, README.md:46-52, crates/gtk-app/src/workspace_command_center.rs:1140-1150
Session States
Sessions progress through a specific state machine to handle streaming output and tool execution:
- Starting: Initializing the PTY and harness.
- Running: Active process execution.
- Streaming: Real-time output being sent to the UI.
- Waiting-for-input: Harness is idle and ready for user commands.
- Tool-running: The agent is currently executing a repository tool (e.g.,
grep,cargo test). - Interrupted/Failed/Exited: Terminal states for the process.
Sources: progress.md:39-44
Configuration & Customization
Archductor utilizes a multi-layered configuration system based on TOML files to define repository behavior and agent instructions.
Settings Layers
- Shared Settings (
.archductor/settings.toml): Committed to the repository; defines team-wide scripts, default branches, and naming templates. - Local Settings (
.archductor/settings.local.toml): Ignored by Git; used for machine-specific overrides like executable paths and API keys. - Prompt Packs: External TOML files containing reusable sets of agent instructions (e.g.,
strict-review,docs-heavy).
Sources: README.md:104-108, crates/core/src/settings.rs:200-215
Customization Domains
Configuration is divided into logical sections that the GTK app consumes to alter the UI and workflow:
- Naming: Templates for branch names (
{prefix}/{type}-{slug}) and workspace naming styles (e.g., "city" names). - Automation: Hooks for
pre-merge,post-checkout, andauto-setupflags. - Merge Rules: Blockers that prevent PR merging if there are open todos, unresolved comments, or failing checks.
- View: UI preferences including theme (Light/Dark/System), accent colors, and font densities.
Sources: crates/core/src/settings.rs:90-160, README.md:155-165
Operational Concepts
Spotlight Testing
Spotlight is a specialized mode for projects that must run from the repository root rather than a worktree. It tracks patches against a clean root, allowing developers to switch between workspace contexts while maintaining a single primary checkout. It includes mechanisms for checkpoint, apply, sync, and repair of tracked workspace patches.
Sources: README.md:183-186, progress.md:112-115
Linked Directories
When a task requires context from another repository (e.g., a frontend workspace needing access to a backend workspace), Archductor uses Linked Directories. These are materialized as symlinks under .context/linked-directories/ and exposed via environment variables like ARCHDUCTOR_LINKED_DIRECTORY_<NAME>.
Sources: progress.md:129-138, README.md:195-200
PR Readiness & Attention
The system generates Readiness Summaries for GitHub Pull Requests. This concept involves aggregating:
- Status Rollups: Combining CI checks, deployments, and commit statuses.
- Review Threads: Tracking unresolved comments and review decisions.
- Attention Section: A prioritized list of failing deployments or requested changes that require immediate agent or developer action.
Sources: progress.md:46-60, crates/gtk-app/src/workspace_command_center.rs:1645-1665
The sequence above demonstrates the transition from a conceptual "Task" to a functional "Workspace" environment.
Sources: README.md:213-228, claude/CLAUDE.md:20-31
Conclusion
The Terminology & Concepts of Linux Archductor center on the strict isolation of work via Workspaces and the orchestration of parallel agent Sessions. By distinguishing between the static Repository configuration and the dynamic Running Environment, Archductor provides a robust framework for managing complex, multi-stream development tasks within a single unified desktop interface.