Linked Directories
Relevant source files
The following files were used as context for generating this wiki page:
Linked Directories is a feature in Linux Archductor designed to facilitate multi-repository or multi-workspace workflows. It allows a source workspace to establish a formal connection to another active workspace, enabling agents and scripts to read or edit related codebases (e.g., a frontend and backend checked out in separate workspaces).
These links are persisted in the application's SQLite database and materialized as filesystem symlinks within the workspace's private context directory. This enables seamless cross-workspace communication and context sharing for parallel coding agents.
Sources: progress.md, README.md
Architecture and Materialization
When a link is created between two workspaces, the system performs two primary actions: persistence and materialization. The relationship is recorded in the SQLite database to ensure the link persists across application restarts. Physically, the link is materialized as a symlink located at .context/linked-directories/<target-workspace-name> within the source workspace's directory.
Environment Variable Exposure
Linked directories are automatically exposed to setup/run scripts, terminal commands, and agent sessions (Shell, Codex, Claude, Cursor) through specific environment variables.
| Variable | Description |
|---|---|
ARCHDUCTOR_LINKED_DIRECTORIES | Newline-separated list of workspace=/path entries for all linked workspaces. |
ARCHDUCTOR_LINKED_DIRECTORY_<NAME> | The absolute path to a specific linked workspace, where <NAME> is the uppercase workspace name. |
Sources: progress.md, README.md
Data Flow Diagram
The following diagram illustrates the relationship between the application database, the physical worktrees, and the environment variables provided to agent processes.
Explanation: This diagram shows how a link established in the application is reflected both as a filesystem symlink and as environment variables available to agents.
Sources: progress.md, README.md, crates/cli/src/main.rs:1049-1060
CLI Interface
The CLI provides three primary subcommands under the workspace command group to manage linked directories. These commands interface directly with the WorkspaceStore.
Commands
- link-dir: Connects a source workspace to a target workspace.
- unlink-dir: Removes the connection between a source and target workspace.
- linked-dirs: Lists all existing links for a specific workspace.
Usage Examples
# Link a backend workspace to a frontend workspace
linux-archductor workspace link-dir frontend backend
# List links for the frontend workspace
linux-archductor workspace linked-dirs frontend
# Remove the link
linux-archductor workspace unlink-dir frontend backend
Sources: README.md, crates/cli/src/main.rs:242-252, crates/cli/src/main.rs:567-585
GTK User Interface
The GTK application features a dedicated "Linked Directories" panel within the workspace command center, typically located in the chat or terminal columns.
Components
- Links View: A monospace text view displaying currently active links, showing the target workspace name and its absolute physical path.
- Target Entry: A text input field where users can type the name of the workspace they wish to link.
- Action Buttons:
- Link: Triggers
store.link_workspace_directory. - Unlink: Triggers
store.unlink_workspace_directory.
- Link: Triggers
The UI updates the view immediately after an action is performed and notifies the RefreshHub to synchronize other parts of the application.
Sources: crates/gtk-app/src/workspace_command_center.rs:1145-1234
UI Interaction Logic
Explanation: The sequence of events when a user manually links two directories via the GTK interface.
Sources: crates/gtk-app/src/workspace_command_center.rs:1175-1200
Data Model
The LinkedDirectory structure represents the record of a link retrieved from the database.
| Field | Type | Description |
|---|---|---|
id | i64 | Unique identifier for the link record. |
workspace_name | String | Name of the source workspace. |
workspace_path | PathBuf | Absolute path to the source workspace root. |
target_workspace_name | String | Name of the workspace being linked to. |
target_workspace_path | PathBuf | Absolute path to the target workspace root. |
link_path | PathBuf | The absolute path to the materialized symlink. |
Sources: crates/cli/src/main.rs:1049-1060, crates/gtk-app/src/workspace_command_center.rs:18
Conclusion
Linked Directories provide a critical infrastructure for managing complex, multi-component projects within the Archductor workflow. By combining SQLite persistence with physical symlinks and environment variable injection, the system ensures that parallel coding agents have the necessary filesystem access and context to perform cross-workspace tasks efficiently.
Sources: progress.md, README.md