> ## Documentation Index > Fetch the complete documentation index at: https://docs.perceo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Running work in parallel > Ports, copied files, sibling conflicts, layouts, and the shortcuts that make several workspaces manageable. One workspace is a nicer terminal. Five at once is the reason to install anything. ## Why worktrees instead of branches Switching branches in one checkout mutates shared state: the working tree, the index, `node_modules`, the dev server, and the agent's idea of what it just wrote. An agent that is mid-turn when you switch branches produces garbage, and you find out at review time. A Git worktree gives each branch its own directory backed by the same object store. No stashing, no rebuilding on switch, and an agent can keep running in one workspace while you review another. The cost is disk and one dependency install per workspace — which is what `[scripts] setup` is for. ## The four things that collide ### 1. Ports Every workspace gets a reserved block of ports. Allocation starts at **42000**, hands out **10 ports per workspace** by default, skips blocks another workspace already holds, and skips blocks whose ports are actually in use. `$ARCHDUCTOR_PORT` is the base of the block. ```toml theme={"dark"} [scripts] run = "pnpm dev --port $ARCHDUCTOR_PORT" [customization.workspace_defaults] port_block_size = 20 # one workspace runs app + api + db + worker ``` Derive the rest from the base rather than hardcoding: ```bash theme={"dark"} API_PORT=$((ARCHDUCTOR_PORT + 1)) DB_PORT=$((ARCHDUCTOR_PORT + 2)) ``` If two workspaces fight over a port, the `run` script hardcoded one. There is no other cause. ### 2. Gitignored local files A new worktree contains tracked files only. Your `.env`, local config, and certificates are not there. Two sources of copy patterns, and they are **combined, not ranked** — the patterns from both are concatenated and matched against the repository's gitignored files: | Source | Behavior | | - | - | | `.worktreeinclude` in the repository root | Its lines are added to the pattern list | | `file_include_globs` in `.archductor/settings.toml` | Its globs are added too — having a `.worktreeinclude` does not disable it | | Neither configured | Nothing is copied. `.env*` is scaffolded into a new `settings.toml`, but it is not a runtime fallback | Lines starting with `!` or `#` in `.worktreeinclude` are discarded, so gitignore-style negation does not work. Once a pattern matches, the file is copied — there is no way to exclude it again. Only gitignored files are copied. Build output and dependency directories are deliberately excluded — reproducing them with `[scripts] setup` is faster and does not carry stale artifacts between branches. If a workspace genuinely cannot start without a file, list it in `env_file_refs`. That turns a missing file into a launch failure with a clear message instead of an application that boots with empty configuration. ### 3. Two agents editing the same file Nothing stops it, and nothing should — sometimes it is what you want. What Archductor does is tell you before you merge. The Changes panel shows **sibling conflicts**: other in-flight workspaces that touched files you also touched. ```bash theme={"dark"} archductor conflicts ``` Check this before opening the pull request, not after CI turns red. When two workspaces genuinely overlap, the fix is usually to merge the smaller one first and rebase the other, not to coordinate the two agents. There is a lighter version of the same signal inside one workspace: declare what a session intends to touch and get an advisory warning when two sessions overlap. ```bash theme={"dark"} archductor archcar session-areas --area src/auth archductor archcar overlaps ``` ### 4. You The binding constraint is review capacity, not machine capacity. Four workspaces producing diffs faster than you can read them is worse than two, because unreviewed agent output accumulates into a merge problem you cannot delegate. Practical ceiling for one person: about as many workspaces as you can hold the intent of at once — usually three to five. ## Moving between workspaces | Keys | Action | | - | - | | `mod+1` … `mod+9` | Jump to workspace 1–9 | | `mod+alt+↑` / `mod+alt+↓` | Previous / next workspace | | `mod+k` | Command palette | | `mod+n` | New workspace | | `mod+l` | Focus the chat input | | `mod+enter` | Send immediately — steer the running turn | | `mod+shift+d` | Changes / diff | | `mod+shift+p` | Create or refresh the pull request | | `mod+j` | Toggle the terminal panel | | `mod+/` | Full shortcut list | `mod` is Cmd on macOS, Ctrl elsewhere. Rebind in **Settings → Shortcuts**. Overrides are stored per machine, not in `.archductor/settings.toml` — a keymap is a personal choice and should not travel with the repository. The format is `action = chord`, one per line or separated by `;` or `,`: ``` palette = mod+shift+k terminal = mod+` ``` Every chord needs a modifier. Assigning a chord another action already holds clears the old binding rather than leaving the keymap ambiguous. ## Layouts Four built-in layouts, because "review three diffs" and "watch a long agent run" want different screens. | Preset | Shape | Use it for | | - | - | - | | **Code** | Chat centre, inspector right (Summary / Files / Changes / Checks), PR strip, terminal dock | Default. Driving one agent. | | **Wide** | Files left, chat centre, inspector right, terminal along the bottom | Wide monitors; keeping the file tree visible. | | **Review** | Files left, **Changes** centre, chat demoted into the right stack | Reading a finished diff. | | **Watch** | Terminal centre, chat bottom, Summary and Checks right | Long agent runs or a flaky test loop. | Built-ins are immutable. Dragging, hiding, or resizing a panel while one is active forks it once into ` edited`, so **Code** always survives as a recovery baseline. Preset definitions sync through the daemon; which preset is active and how wide your regions are stay local to the device — the same layout should not follow you onto a laptop with a different screen. ```bash theme={"dark"} archductor layout presets --repository my-app archductor layout show wide archductor layout set-default review --repository my-app archductor layout delete custom-my-layout ``` `set-default` writes `customization.view.default_layout_preset` into the committed `.archductor/settings.toml`, preserving other keys. It is a team decision, so it belongs in the committed file. ## Splitting and joining work **Fork a chat** when a conversation is worth branching — you want a second approach from message 40 without losing the first. ```bash theme={"dark"} # Second chat, same workspace and branch: archductor archcar fork-chat --through-message-id # Second chat in a new workspace, branched off the source branch: archductor archcar fork-chat --through-message-id \ --new-workspace --workspace-name try-b --workspace-branch try/b ``` The fork carries the conversation up to that point, so the new agent starts with the context rather than a summary of it. In the app it is on a message's menu. **Link workspaces** when one needs to read another's checkout — a frontend workspace that needs a backend branch still in flight. The target is symlinked into `.context/linked-directories/`. ```bash theme={"dark"} archductor workspace link-dir frontend backend-api archductor workspace linked-dirs frontend ``` Both workspaces must be active. This is a read path for agents and build tooling, not a substitute for multi-repo projects — the product model is one repository per project. **Duplicate a workspace** to get the same starting point twice: ```bash theme={"dark"} archductor workspace duplicate fix-auth fix-auth-alt --branch fix/auth-alt ``` ## Testing in your real environment Some setups only exist in the main checkout — a simulator, a docker-compose stack, a seeded database. Spotlight testing applies one workspace's tracked changes onto the root checkout so you can exercise them there, then reverts. ```toml theme={"dark"} spotlight_testing = true ``` ```bash theme={"dark"} archductor archcar spotlight-start archductor archcar spotlight-status archductor archcar spotlight-stop ``` It requires a clean root working tree and refuses if the workspace has no tracked changes. One repository has at most one active spotlight session; starting a second stops the first. A checkpoint is taken before the patch is applied. ## Names An unnamed workspace gets a city name (`madrid`, `lisbon`, …) chosen from the ones not currently in use, rather than `workspace-3`. Names are how you find things a week later. ```toml theme={"dark"} [customization.naming] workspace_name_style = "city" # any other value falls back to workspace, workspace-1, … [customization.workspace_defaults] branch_prefix = "pk" # default "lc"; issue workspaces become pk/gh-issue-431 ``` Explicit `--name` and `--branch` always win. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.