Run the Factory

Finish Set up the Factory first. Run the Factory from the repository's main checkout, not from a worktree.

1. Start it

cd path/to/your-repo
archdev agents factory run

archdev run does the same thing.

What happens, in order:

1. Checks the repository. It must be a git repository with archdev.json. If not: Factory mode needs an initialized repository. Run `archdev jobs setup` first.
2. Syncs to origin/main. You must be on main or a branch that tracks origin/main. It fetches and fast-forwards or rebases that branch, then prints Synced <path> (<branch>) to origin/main: <old> → <new>, N pulled in. It never stashes. If the checkout is behind and has uncommitted tracked changes, a detached HEAD or local merge commits, it stops and says why. To start without syncing, add --no-rebase.
3. Reads the committed configuration. It checks the branch_update pipeline in archdev.json at HEAD and warns if Tasks would not open pull requests.
4. Checks the daemon. If the daemon isn't installed or the repository isn't registered, it asks: Install the local ArchDev daemon and register this repository for Jobs now? [y/N].
5. Checks your sign-in. If you're signed out: Not authenticated. Run `archdev auth login` first.
6. Takes the repository lock. Only one Factory runs per repository. A second one fails with Factory project lock is already held for <path>.
7. Opens the overseer. The first time, a 4-page guide appears; reopen it later with /help factory. The Factory panel is open on the right, and the workers start.

2. Give it work

There are two ways to give the Factory work:

• New work: type the goal at the prompt. The overseer drafts Tasks and opens a browser review. See Plan work as Tasks.
• Existing Tasks: nothing to do. In the default auto dispatch mode, workers claim every ready Task assigned to you in this repository, in priority order.

While the overseer is working, press Enter to queue a message that steers it and Esc to stop its current turn. Esc doesn't quit.

3. Watch it

The Factory panel is open on the right. Ctrl-F hides or shows it. To use its keys, press Tab from an empty prompt (or click the panel). Esc hands the keyboard back to the prompt.

In the panel, press 1–4 or Tab to switch tabs, ↑↓ to select and Enter to open details.

What a Task goes through (a conceptual flow; the panel uses the groups above):

ready ─▶ leased (worker building) ─▶ submitted (daemon verifying) ─▶ in_review (PR open) ─▶ done (merged)

• Worktrees: ~/.archdev/factory-worktrees/<task-id>-<suffix>, on branch factory/<task-id>.
• Commits: the worker's own commits, plus one factory: <task name> commit made when the worker calls done.
• Pull requests: opened by the daemon after verification. The body starts with Epic: and Task: links. Find them at archdev.ai/pulls or on GitHub.
• Away from the terminal: archdev.ai/tasks shows Task status and the notification bell lists what needs you (needs the Tasks and Projects experimental feature; turn it on), and archdev.ai/minimap shows Tasks moving through backlog, workers, validation and review.

Answer questions

A Task pauses when it needs a decision about credentials, spending, live infrastructure, an irreversible action, a product choice, or a sign-off the Task names. Every question comes with a recommended answer and the reason for it.

In the overseer: open Needs you, select the item and press Enter, then:

From any terminal:

archdev tasks inbox                                # paused Tasks, oldest first
archdev tasks answer <task-id> "Use the read replica"
archdev tasks answer <task-id> --accept-recommended

In the browser: this needs the Tasks and Projects experimental feature; turn it on. Open the notification bell at the top of any page. Needs you lists everything waiting on you; select an item to open it beside the list and answer it there, without leaving the page:

Or open one Task at archdev.ai/tasks/<task-id> and answer in its What this needs from you panel:

What happens next: your answer is added to the Task as a [human:answer] comment and the Task reopens. The next worker gets your answer as a requirement.

Stopped pull requests

When the daemon can't fix a pull request's CI failures or review feedback on its own, the PR appears in Needs you:

Choose how Tasks are dispatched

The same settings can go in archdev.json under factory (workers, dispatch, autonomy, push_transport). Command-line flags override them.

A typical first run, keeping control of which Tasks start:

archdev agents factory run --workers 2 --dispatch manual

Once you trust the plan and the checks:

archdev agents factory run --workers 6 --autonomy auto

Change settings while it runs

The Factory re-reads archdev.json, archdev.local.json and ~/.archdev/archdev.json when they change. You don't need to restart it for these:

Every other factory setting, and origin, modelAliases, publish.base and deploy_targets, keeps the value the Factory started with. The Factory log (~/.archdev/logs/archdev.log) records factory.config.reloaded with the keys it applied, and factory.config.restart_required with requires restart: <keys> for the rest. If the edited file is invalid, it records factory.config.reload_failed with the error and the overseer keeps its last valid settings. Fix the file quickly anyway: a worker reads archdev.json itself when it starts a Task, and can't start one while the file is invalid. The daemon logs daemon.config.reloaded and daemon.config.reload_failed in ~/.archdev/logs/daemon.log.

4. Stop and resume

Stop: press Ctrl-C twice within a second. Workers get 30 seconds to shut down cleanly. On exit it prints:

Session ID: <id>
Resume with: archdev agents resume <id>

From another terminal:

archdev agents factory status   # which process holds the lock
archdev agents factory stop     # graceful stop (add --force to kill after --timeout seconds)

Resume the same overseer conversation:

archdev agents resume <session-id>

Stopping the Factory doesn't stop the daemon. Pull requests that are already submitted keep getting verified, published and followed up.

Commands while it runs

For errors, see Factory troubleshooting.