Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Linux Archductor is a desktop control plane designed for Linux environments using GTK4 and libadwaita. It enables users to run parallel coding agents within isolated Git worktree workspaces. The installation process ranges from using pre-built AppImages and native packages to building from source for development purposes.
The setup involves configuring both the system environment (dependencies like git, gh, and sqlite) and repository-specific settings. Once installed, the application manages project state through a local SQLite database and persists logs and configuration in standard XDG directories.
Sources: README.md:1-12, README.md:118-120, claude/CLAUDE.md:105-110
System Requirements
Archductor relies on several external CLI tools to perform its core functions. These must be installed and, in the case of GitHub and AI agents, authenticated on the host system.
| Tool | Required For |
|---|---|
git | Managing worktrees, branches, diffs, and commits. |
gh | GitHub PR creation, status checks, comments, and merging. |
sqlite | Local state persistence for projects, workspaces, and history. |
openssh | SSH-based repository access. |
codex | Running Codex agent sessions. |
claude | Running Claude Code agent sessions. |
Sources: README.md:154-165, nfpm.yaml:40-52
Pre-installation Checklist
Before running the application, ensure that gh auth login has been executed if GitHub integration is required. AI agents like Codex and Claude Code utilize existing local CLI authentication from the host environment.
Sources: README.md:167-168
Installation Methods
1. AppImage (Recommended)
The AppImage provides a portable binary that includes both the GTK GUI and the CLI interface.
curl -Lo linux-archductor.AppImage \
https://github.com/pranavkannepalli/conductor-arch/releases/latest/download/linux-archductor-x86_64.AppImage
chmod +x linux-archductor.AppImage
sudo mv linux-archductor.AppImage /usr/local/bin/linux-archductor
Launching the AppImage without arguments starts the GUI; passing arguments forwards them to the CLI (e.g., linux-archductor doctor).
Sources: README.md:118-131, packaging/README.md:65-70
2. Native Packages
Native packages are available for several distributions. Dependencies are automatically handled by the package manager.
- Debian/Ubuntu (.deb): Requires
libgtk-4-1andlibadwaita-1-0. - Fedora/RPM (.rpm): Requires
gtk4andlibadwaita. - Arch Linux (AUR): Available via
makepkg.
Sources: nfpm.yaml:40-52, packaging/README.md:46-59
3. Build from Source
Building from source requires the Rust toolchain and development headers for GTK4 and libadwaita.
# Example for Ubuntu/Debian
sudo apt install git gh sqlite3 openssh-client pkg-config libgtk-4-dev libadwaita-1-dev
curl https://sh.rustup.rs -sSf | sh
# Build
git clone https://github.com/pranavkannepalli/conductor-arch
cd conductor-arch
cargo build --workspace --release --locked
Sources: README.md:133-149
Repository Initialization
Once the application is running, a codebase must be registered as a "Project". This involves creating an Archductor entry that maps to a Git repository.
The initialization process creates a .archductor/ directory in the repository root to store shared settings and prompt packs.
Sources: README.md:104-106, crates/core/src/settings.rs:242-260
Configuration Files
Archductor uses a layered configuration model:
- Shared Settings:
.archductor/settings.toml. Committed to Git for team consistency. - Local Overrides:
.archductor/settings.local.toml. Used for machine-specific secrets or paths; should be gitignored. - Worktree Include:
.worktreeinclude. Defines which gitignored files (like.env) should be copied into new workspaces.
Sources: README.md:170-178, crates/core/src/settings.rs:188-193
Data and Log Locations
Archductor follows standard Linux directory conventions for persisting its internal state and logs.
| Type | Location |
|---|---|
| Config | ~/.config/linux-archductor/config.toml |
| Database | ~/.local/share/linux-archductor/linux-archductor.db |
| Logs | ~/.local/state/linux-archductor/logs/<workspace>/ |
| Cache | ~/.cache/linux-archductor/ |
| Workspaces | ~/archductor/workspaces/<repo>/<workspace>/ |
Sources: README.md:405-411, crates/gtk-app/src/main.rs:608-615
Validation and Diagnostics
The doctor command is provided to verify that the environment is correctly set up and all required dependencies are reachable.
linux-archductor doctor
This command checks for the presence of git, gh, sqlite, and openssh, and identifies the host distribution to provide specific installation advice if tools are missing.
Sources: README.md:364, crates/cli/src/main.rs:1257-1279, scripts/release-readiness.sh:58-62
Summary
Installation of Linux Archductor is primarily focused on the Linux desktop environment, utilizing AppImage or native packages for deployment. Setup requires a combination of system-level CLI tools (git, gh) and repository-level configuration within the .archductor/ directory. Once initialized, the system provides a robust environment for managing parallel agent-driven development tasks through isolated worktrees and local state management.