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

# Core workflow

> How projects, workspaces, branches, and agent sessions fit together.

The normal path is repository first.

<Steps>
  <Step title="Add or clone a repository">
    From the Projects page, point at an existing local folder or clone a Git URL.
    One project wraps one repository.
  </Step>

  <Step title="Configure the project">
    Set scripts, prompts, providers, and workspace defaults. See
    [Project setup](/archductor/project-setup).
  </Step>

  <Step title="Create a workspace">
    From a branch, a prompt, a GitHub issue, a GitHub PR, or a Linear issue.
  </Step>

  <Step title="Start sessions">
    Shell, Codex, or Claude Code, one or several, inside that workspace.
  </Step>

  <Step title="Review">
    Changed files, diffs, todos, comments, checks, and sibling conflicts.
  </Step>

  <Step title="Ship and archive">
    Create or merge the PR, archive the workspace, then repeat.
  </Step>
</Steps>

Normal work happens in the app. The CLI stays available for automation, debugging,
and fallback workflows.

## Workspaces and branches

One workspace is one branch and one Git worktree for one stream of work. That is
what keeps tasks independently reviewable and stops agent sessions from trampling
each other.

* Each workspace gets its own Git worktree, branch, and `.context` directory.
* Workspaces for the same repository get separate stable `ARCHDUCTOR_PORT` ranges,
  so two dev servers do not collide.
* You can run multiple workspaces for the same repository in parallel.
* Multiple sessions inside one workspace intentionally share branch state.

<Tip>
  Treat each workspace as one shippable unit. If two changes should be reviewed
  separately, they should live in separate workspaces.
</Tip>

<Warning>
  Workspace `.context/` files are local scratch context. Keep them gitignored.
</Warning>

## Sessions and harnesses

Claude Code, Codex, and Shell are harnesses running inside the workspace. Archductor
owns everything around them: the workspace, branch, terminal, diff, checks, PR
state, and archive and history flow.

* Start multiple Shell, Codex, or Claude Code sessions in one workspace.
* Use the embedded terminal, setup/run/stop controls, logs, and process lists.
* Stage review comments, failing checks, or PR comments into a selected agent
  session instead of copy-pasting them.
* Persist transcript history and restore archived workspace context later.

## Review and merge

Review happens in the GUI. Changed files, diffs, local comments, GitHub comments,
checks, conflicts, todos, PR state, merge, and archive are one flow rather than
five separate tools.

Sibling workspace conflicts are surfaced too — if another in-flight workspace
touches the same files, you see it before the merge, not after.