Linux Archductor Overview

Relevant source files

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

• README.md
• progress.md
• claude/CLAUDE.md
• crates/cli/src/main.rs
• crates/gtk-app/src/main.rs
• crates/core/src/codex_tui.rs

Linux Archductor is a desktop control plane designed for running parallel coding agents across isolated Git worktree workspaces. It provides a Linux-native environment, built with GTK4 and libadwaita, to manage multiple streams of work within a single codebase by isolating tasks into distinct workspaces. Each workspace maintains its own Git branch, directory, terminal, and agent sessions (such as Codex or Claude Code), allowing developers to review diffs, manage GitHub Pull Requests, and track todos within a unified interface.

Sources: README.md:1-12, claude/CLAUDE.md:14-19, packaging/flatpak/io.github.pranavkannepalli.linux-archductor.appdata.xml:8-13

Core Architecture and Data Model

The system is structured around a hierarchical relationship model that maps physical Git constructs to Archductor management units. Data is persisted using a SQLite-backed store for repositories, workspaces, processes, and review states.

Relationship Model

• Project: The Archductor entry for one codebase. It owns repository-level settings, scripts, and the list of workspaces.
• Repository: The underlying Git codebase. One project contains exactly one repository.
• Workspace: An isolated copy of a project for a specific task. One repository can contain many workspaces.
• Branch/Working Tree: Each workspace maps to one Git branch and one physical working tree on disk created via Git worktrees.
• Running Environment: Includes terminals, agent sessions, and scripts running within a workspace.

Sources: README.md:14-26, claude/CLAUDE.md:27-43, progress.md:147-151

The diagram represents the structural hierarchy of Linux Archductor, showing how a single Project manages multiple isolated Workspaces through Git worktrees. Sources: README.md:16-24, claude/CLAUDE.md:36-41

System Components

The project is divided into three primary crates and a core server for handling asynchronous agent sessions.

Component	Responsibility	Relevant Files
crates/core	Persistence (SQLite), PTY handling, Codex TUI parsing, harness building.	crates/core/src/codex_tui.rs
crates/gtk-app	Native UI (GTK4/libadwaita), workspace visualization, chat/terminal surfaces.	crates/gtk-app/src/main.rs, src/projects.rs
crates/cli	Automation, debugging, and fallback workflows for environment management.	crates/cli/src/main.rs
Archcar	A server-client protocol for managing PTY-backed agent sessions (archcar-serve).	crates/cli/src/main.rs:770-780()

Sources: claude/CLAUDE.md:92-108, crates/gtk-app/src/main.rs:163-176

Workspace Lifecycle and Workflow

The Archductor workflow focuses on task isolation and agent integration. Workspaces can be created from various sources, including branches, GitHub issues, GitHub PRs, or LLM prompts.

Workspace Creation Flow

1. Source Preflight: Checks for gh auth and LINEAR_API_KEY readiness.
2. Worktree Initialization: Archductor creates a Git worktree and a .context directory.
3. Environment Setup: Stable port allocation (via ARCHDUCTOR_PORT) and environment variable injection.
4. Task Execution: Running setup scripts, starting agent sessions (Codex, Claude, Shell).

Sources: README.md:65-75, progress.md:147-157, crates/cli/src/main.rs:1078-1110

Flowchart showing the lifecycle of an Archductor workspace from creation to archiving. Sources: README.md:65-75, progress.md:147-160

Agent Integration and Codex TUI

Archductor uses a PTY-backed harness to run agents. It implements specialized parsing for Codex TUI output to render structured events in the GTK application.

Codex Inline Events

The codex_tui module parses raw terminal output into structured CodexInlineEvent types:

• Tool: Calls to functions like exec_command or mcp tools.
• Skill: Announcements of using specific "superpowers" or skills.
• FileChange: Summaries of added, edited, or deleted files, including diff line counts.
• ContextUsage: Token usage and context window percentages.

Sources: crates/core/src/codex_tui.rs:3-60, progress.md:32-40

PTY Session State Machine

Agent sessions transition through an explicit state machine:
Starting -> Running -> Streaming -> WaitingForInput -> ToolRunning -> Exited/Failed.

Sources: progress.md:32-35, crates/cli/src/main.rs:782-800

Configuration and Customization

Configuration is handled via TOML files at the repository level (.archductor/settings.toml) and local overrides (.archductor/settings.local.toml).

Field Section	Description	Default/Supported Values
[scripts]	Commands for setup, run, test, lint.	run_mode = "concurrent"
[customization.naming]	Templates for branches and commits.	workspace_name_style = "city"
[customization.view]	UI preferences for the GTK app.	theme = "system", accent_color = "green"
[customization.merge_rules]	Conditions for merging PRs.	block_on_open_todos = true

Sources: README.md:104-180, crates/gtk-app/src/main.rs:60-110

Environment Variables

Processes running within a workspace receive specialized context variables:

• ARCHDUCTOR_WORKSPACE_PATH: Absolute path to the worktree.
• ARCHDUCTOR_PORT: Base port for the workspace.
• ARCHDUCTOR_WORKING_DIRECTORY: Subdirectory for monorepo support.

Sources: README.md:198-210, progress.md:188-195

Conclusion

Linux Archductor provides a structured, multi-workspace environment for agentic software development on Linux. By leveraging Git worktrees for physical isolation and a specialized PTY harness for agent communication, it enables developers to manage complex, parallel coding tasks while maintaining clear task boundaries and integrated review workflows.

Sources: README.md:77-80, claude/CLAUDE.md:15-20