Your first workspace

Budget an hour the first time. Most of it goes into step 3 — the repository settings — which is the part that pays off on every workspace afterwards.

1. Authenticate the tools it drives

Archductor shells out to CLIs you have already authenticated. It stores no credentials and proxies no API calls.

gh auth login          # required for anything pull-request shaped
codex login            # or: claude auth login
archductor doctor      # environment check
archductor setup       # the readiness probe the app's first-run gate uses

archductor setup --recheck re-reads the process environment first, which is what you want immediately after installing a tool in another terminal.

You do not need any agent CLI to get value out of Archductor. Isolated worktrees, the diff surface, checks, and the pull-request flow all work with Shell sessions alone.

2. Add the repository

archductor repo add ./my-app --name my-app
archductor repo doctor my-app

In the app: the Projects page, pointing at an existing folder or cloning a Git URL. One project wraps one repository. Read repo doctor rather than skimming it. It tells you whether the default branch, the remote, and the worktree parent directory are what you assume — all three are baked into every workspace created afterwards.

3. Configure it before creating workspaces

A workspace picks up configuration when it is created, so it is much faster to write the file first than to fix three workspaces later.

.archductor/settings.toml

file_include_globs = """
.env
.env.local
"""

[scripts]
setup = "pnpm install"
run   = "pnpm dev --port $ARCHDUCTOR_PORT"
test  = "pnpm test"
lint  = "pnpm lint"

Four things earn their keep immediately:

setup runs once per new workspace. A fresh worktree has no node_modules, no target/, no .venv — nothing gitignored. Without a setup script, every new workspace starts broken.
file_include_globs lists gitignored files to copy from the main checkout into each new worktree. This is how .env gets there. Only gitignored files are ever copied; tracked files come from Git.
$ARCHDUCTOR_PORT is a stable per-workspace port. Use it in run or two workspaces will fight over 3000.
test and lint become the workspace’s checks. There is no separate checks configuration — these keys are it.

Full schema in Project setup and the settings reference.

4. Create the workspace

archductor workspace create my-app \
  --name fix-auth --branch fix/auth --base main

Or from a prompt, a GitHub issue, a GitHub pull request, or a Linear issue — --prompt, --from-issue, --from-pr, --from-linear. Issue-sourced workspaces seed the branch name and the agent’s first message from the issue, which is worth more than it sounds when you create a dozen a day. You get a Git worktree, a branch, a .context/ directory for scratch state, a reserved port block, and your copied local files.

One workspace is one reviewable unit. If two changes should land as two pull requests, they need two workspaces. Several chats inside one workspace is fine — they share the branch on purpose.

5. Start an agent

archductor session start fix-auth --kind codex
archductor session send fix-auth --kind codex \
  "Fix the token expiry off-by-one in the auth middleware"

In the app this is the Chat panel. Either way the message enters a durable queue owned by the daemon, not a terminal buffer. It survives the app restarting, and it is delivered when the agent is ready for it rather than being typed into the middle of a running turn. That distinction — queueing versus steering — is the thing most worth understanding early. See Agent sessions.

6. Review

archductor diff fix-auth                 # unstaged
archductor diff fix-auth --uncommitted   # staged and unstaged, vs HEAD
archductor checks fix-auth

The Changes panel is the same data. Prefer reviewing in the app: the panel also carries todos, local review comments, sibling-workspace conflicts, pull-request checks, and GitHub PR comments — and any of them can be pushed straight into the agent’s input queue instead of being copy-pasted. Sibling conflicts are the underrated one. If another in-flight workspace has touched the same files, you see it here, before the merge.

archductor archcar workspace-diff inverts the default: it shows everything against the review base, and takes --uncommitted to narrow. Use it when you want the whole branch.

7. Ship

archductor archcar push-branch fix-auth      # PR creation needs an upstream
archductor pr create fix-auth --title "Fix auth token expiry" --draft
archductor pr checks fix-auth
archductor pr merge fix-auth --method squash
archductor workspace archive fix-auth --remove-worktree

pr create --from-context fills the title and body from the generated draft — the summary, tasks, per-agent contributions, check results, and recorded risks. Better than a hand-written stub when the work spanned several sessions.

Merge blockers

Enforced by pr merge. Two are on by default, which surprises people:

Rule	Default
`block_on_open_todos`	on
`block_on_open_comments`	on
`block_on_failed_checks`	off
`block_on_pending_checks`	off

[customization.merge_rules]
block_on_open_todos = false
block_on_failed_checks = true

Archiving keeps the record and the transcripts; --remove-worktree reclaims the disk. archductor workspace restore brings it back.

When it goes wrong

Ordered by how often it is the answer.

Symptom	Check
Workspace launch fails immediately	An `env_file_refs` entry points at a file that does not exist. That is a hard failure by design — a missing `.env` should not silently produce a half-working workspace.
New workspace has no dependencies	No `[scripts] setup`, or setup failed. `archductor logs <workspace>`.
Agent starts and dies	The provider CLI is not on the daemon’s `PATH`. Run `archductor setup`, or `archductor service doctor` if the daemon runs as a service.
Two workspaces fight over a port	The `run` script hardcoded a port instead of using `$ARCHDUCTOR_PORT`.
Pull-request commands fail	`gh auth status`, or the branch has no upstream — `archductor archcar push-branch <workspace>`.
Everything looks stale	`archductor archcar inventory-snapshot` forces a round-trip through the daemon; the client spawns it if it is not running. If that fails, `archductor service status` and `archductor service doctor`.

archductor archcar processes <workspace> lists every setup, run, check, and session process the daemon believes it owns — the fastest way to find a process that outlived its session.

Running work in parallel

The reason to install any of this.

Project setup

Scripts, copied files, prompts, checks, merge rules.

Get started

Guides

Reference

Your first workspace

1. Authenticate the tools it drives

2. Add the repository

3. Configure it before creating workspaces

4. Create the workspace

5. Start an agent

6. Review

7. Ship

Merge blockers

When it goes wrong

Next

Running work in parallel

Project setup

​1. Authenticate the tools it drives

​2. Add the repository

​3. Configure it before creating workspaces

​4. Create the workspace

​5. Start an agent

​6. Review

​7. Ship

​Merge blockers

​When it goes wrong

​Next

Running work in parallel

Project setup

1. Authenticate the tools it drives

2. Add the repository

3. Configure it before creating workspaces

4. Create the workspace

5. Start an agent

6. Review

7. Ship

Merge blockers

When it goes wrong

Next