System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Linux Archductor is a local desktop control plane designed for parallel coding agents (such as Codex and Claude Code) utilizing Git worktrees to isolate tasks. The system provides a unified interface for managing multiple repositories, workspaces, and agent sessions, allowing developers to execute complex workflows—ranging from setup and testing to GitHub PR creation and merging—entirely within a specialized environment.
The project is structured as a Rust workspace containing three primary components: a core library for state management and process control, a GTK4/libadwaita graphical application for daily use, and a CLI for automation and fallback workflows. The architecture leverages pseudo-terminal (PTY) backed harnesses to interface with external agent CLIs, persisting structured chat history and system events in a SQLite database.
Sources: README.md:1-12, progress.md:1-15, claude/CLAUDE.md:144-158
Component Hierarchy
The system follows a strict hierarchical relationship model to organize codebases and concurrent tasks. A Project acts as the root entry for a specific codebase, owning repository-level settings. Each project manages a Repository, which in turn contains multiple Workspaces. Each workspace maps to a unique Git Branch and an isolated Working Tree on disk created via Git worktrees. Within a workspace, multiple Processes (agent sessions, terminals, or scripts) run in a shared Running Environment.
Data Relationship Model
The following diagram illustrates the structural relationships between the primary architectural entities:
Sources: README.md:14-27, claude/CLAUDE.md:125-142
Core Architectural Layers
1. Core Library (crates/core)
The core layer serves as the engine of the application. It handles repository and workspace state, pseudo-terminal (PTY) management for agent sessions, and persistence for chat threads and messages. It includes the WorkspaceStore and RepositoryStore for interacting with the SQLite backend.
2. GTK Application (crates/gtk-app)
A native Linux application built with GTK4 and libadwaita. It provides a visual command center including a dashboard, project management, and a rich workspace view with embedded agent chats, terminals, and diff viewers. It utilizes a RefreshHub to synchronize UI updates across different components when underlying state changes.
3. CLI Interface (crates/cli)
The CLI provides a command-line wrapper around the core library. It is used for automation, debugging, and as a fallback for users who prefer terminal-based workflows. It supports workspace lifecycle management, session control, and PR operations.
Sources: claude/CLAUDE.md:154-173, crates/gtk-app/src/main.rs:484-510, crates/cli/src/main.rs:188-210
Process and Session Management
Sessions for coding agents (Codex, Claude, Shell, or Cursor) are managed via an "Archcar" server-client model. This architecture allows the UI to remain responsive while long-running agent processes execute in the background.
Archcar Communication Flow
The system uses an asynchronous bridge to communicate with the Archcar server for session spawning and input/output handling:
Configuration and Customization
Configuration is tiered to support shared team defaults and local developer overrides. Settings are persisted in TOML format within the .archductor/ directory of the repository.
| Configuration Level | Path | Purpose |
|---|---|---|
| Shared Settings | .archductor/settings.toml | Committed team defaults for scripts, prompts, and automation. |
| Local Settings | .archductor/settings.local.toml | Machine-specific overrides, secrets, and provider paths. |
| Prompt Packs | .archductor/prompt-packs/*.toml | Reusable instruction sets for specific agent tasks. |
| Workspace Context | .context/ | Local scratch context (gitignored) for specific workspace tasks. |
Sources: README.md:120-140, crates/core/src/settings.rs:17-65, crates/core/src/settings.rs:281-305
Workspace Lifecycle and Worktree Logic
Workspaces are materialized as real Git worktrees. This allows for complete filesystem isolation, enabling different tasks to have different dependencies or running servers (managed via stable port blocks) simultaneously.
Workspace Creation Logic
Conclusion
The architecture of Linux Archductor provides a robust, Linux-native environment for parallel agent development. By combining Git worktree isolation with a PTY-backed session model and a centralized SQLite state store, the system enables complex, concurrent workflows that remain responsive and persistent. The separation into Core, GTK, and CLI layers ensures that the tool is both developer-friendly for daily use and extensible for automated environments.
Sources: README.md:315-325, claude/CLAUDE.md:175-185