Workspace Management
Relevant source files
The following files were used as context for generating this wiki page:
Workspace Management is the core logic within Linux Archductor for handling isolated development environments. In this system, a Project wraps a single Repository, and that repository can contain multiple Workspaces. Each workspace is an isolated copy of the repository—implemented using Git worktrees—mapped to a specific branch for a single task, issue, or experiment.
The management system facilitates the entire lifecycle of a workspace: from creation via multiple source types (branches, GitHub issues, or AI prompts) to active development (agent sessions, terminal tasks) and finally to conclusion (merging pull requests and archiving). This isolation allows developers and AI agents to work on multiple streams of effort in parallel without file conflicts.
Sources: README.md:12-25, progress.md:14-22
Architecture and Core Concepts
The architecture follows a strict hierarchy where projects own repository settings and the registry of associated workspaces. The state is persisted in a SQLite database, tracking repository paths, workspace status, and process records.
Product Structure Hierarchy
| Level | Component | Description |
|---|---|---|
| 1 | Project | The top-level entry for a codebase. Owns settings and scripts. |
| 2 | Repository | The Git codebase. Can be local, cloned, or from a template. |
| 3 | Workspace | An isolated Git worktree linked to a specific branch. |
| 4 | Environment | The running processes (agents, terminals, scripts) within a workspace. |
Sources: README.md:16-24, progress.md:135-140
Workspace Data Flow
The following diagram illustrates how a user request flows through the GTK interface into the core storage and Git filesystem.
Workspace Creation and Sources
Workspaces can be bootstrapped from various sources. The WorkspaceSourceRequest enum defines the logic for resolving different inputs into a physical Git worktree.
- Branch/Base: Traditional creation from an existing branch or reference.
- GitHub Issue/PR: Fetches metadata from GitHub to auto-generate branch names and workspace context.
- Linear Issue: Integrates with Linear tickets to seed the workspace.
- Prompt: Uses an AI-generated slug and description to initialize the environment.
Sources: crates/gtk-app/src/projects.rs:567-595, progress.md:144-148
Source Preflight and Validation
Before creation, the system performs a "preflight" check to ensure required tools like gh (GitHub CLI) are authenticated and environment variables like LINEAR_API_KEY are set.
Lifecycle Management
Workspaces transition through several states throughout their existence. Management is handled through the Workspace Command Center and the Sidebar.
Core Lifecycle Actions
- Rename: Updates the display name in the SQLite database.
- Duplicate: Creates a new worktree/branch based on the current workspace's state.
- Archive: Moves the workspace to an archived state, optionally removing the worktree but preserving the branch and history.
- Restore: Reactivates an archived workspace.
- Delete: Permanently removes the worktree and database record.
Sources: crates/gtk-app/src/workspace_command_center.rs:1145-1275, crates/gtk-app/src/sidebar.rs:600-750
Workspace Status Transitions
The status of a workspace is tracked via the WorkspaceStatusLine and summarized in "buckets" for the History view.
| Status | Bucket | Criteria |
|---|---|---|
active | Active | Currently has running sessions, scripts, or an open PR. |
active | Backlog | No active processes or open PRs. |
archived | Archived | Explicitly archived by the user. |
Sources: crates/gtk-app/src/history.rs:140-155
Command Center and Runtime
The Workspace Command Center is the primary interface for managing a workspace's running environment. It is divided into several functional panels.
Environment Management Components
- Agents Panel: Launches PTY-backed Shell, Codex, Claude, or Cursor sessions.
- Runtime Panel: Controls
setupandrunscripts defined in.archductor/settings.toml. - Terminal Panel: Provides embedded terminal access with shared environment variables (e.g.,
ARCHDUCTOR_PORT). - Checks/Review Tabs: Manages Pull Request state, GitHub review threads, and local todo items.
Sources: crates/gtk-app/src/workspace_command_center.rs:945-985, crates/gtk-app/src/workspace_command_center.rs:1040-1140, README.md:214-225
Conflict Detection
The system automatically detects file-level conflicts between sibling workspaces (workspaces belonging to the same project). This allows the user to preview changes or copy files from a sibling workspace to resolve overlaps.
Sources: crates/gtk-app/src/workspace_command_center.rs:1880-2050
Implementation Details
The management system relies on the WorkspaceStore struct for database interactions and the RepositoryStore for repository-level metadata.
Workspace Data Model
Derived from crates/core/src/workspace.rs (referenced in GTK implementation):
id: Unique identifier.name: Human-readable name (often a city name or issue slug).path: Absolute path to the Git worktree.branch: The Git branch associated with the worktree.port_base: A stable port range assigned to the workspace.status: Current lifecycle state (active,archived, etc.).
Sources: crates/gtk-app/src/projects.rs:885-895, crates/gtk-app/src/history.rs:115-130
Linked Directories
For complex tasks involving multiple repositories, Workspace Management supports Linked Directories. This materializes symlinks under the .context/linked-directories/ folder, allowing an agent in one workspace to access the checkout of another.
Sources: crates/gtk-app/src/workspace_command_center.rs:1725-1770, progress.md:121-125
Conclusion
Workspace Management in Linux Archductor provides a robust framework for parallelizing development. By combining Git's native worktree capabilities with a centralized SQL management layer and AI agent integration, it ensures that every task remains isolated, documented, and easily transitionable from a local experiment to a GitHub pull request.