> ## 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.

# Your first workspace

> From a fresh install to a merged pull request, and what to configure before you start.

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.

```bash theme={"dark"}
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.

<Note>
  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.
</Note>

## 2. Add the repository

```bash theme={"dark"}
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.

```toml .archductor/settings.toml theme={"dark"}
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](/archductor/project-setup) and the
[settings reference](/archductor/settings-reference).

## 4. Create the workspace

```bash theme={"dark"}
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.

<Tip>
  **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.
</Tip>

## 5. Start an agent

```bash theme={"dark"}
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](/archductor/agent-sessions).

## 6. Review

```bash theme={"dark"}
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.

<Note>
  `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.
</Note>

## 7. Ship

```bash theme={"dark"}
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 |

```toml theme={"dark"}
[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.

## Next

<CardGroup cols={2}>
  <Card title="Running work in parallel" icon="columns-3" href="/archductor/parallel-work">
    The reason to install any of this.
  </Card>

  <Card title="Project setup" icon="sliders-horizontal" href="/archductor/project-setup">
    Scripts, copied files, prompts, checks, merge rules.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.