Set up the Factory

Steps 1, 2 and 5 are once per machine. Steps 3, 4, 6, 7 and 8 run inside the repository, once per repository. Each step gives the command to run, what it does and how to check that it worked.

Before you start

You need:

• macOS, Linux or Windows, with git.
• A GitHub repository checked out locally, with remote origin and default branch main. The built-in verification pipeline publishes to origin/main. For a different base branch, see Custom pipelines.
• The GitHub CLI signed in to an account that can open pull requests on that repository. Check with gh auth status; if you're not signed in, run gh auth login.
• archdev on your PATH (the installer does this), and Node.js on your PATH if you install repository-scoped hooks (step 3).

1. Install the CLI

Check: archdev --version prints a version. If the command is not found, open a new terminal so your PATH is reloaded.

2. Sign in to ArchDev

archdev auth login

What happens: a browser opens to sign in. Over SSH, use archdev auth login --headless and paste the code. Credentials are saved to ~/.config/archdev/credentials.json.

Check:

archdev auth status

Status: Authenticated (org)
Organization: <your organization>
Email: <you>

If Organization is missing or wrong, ask an administrator to check your membership before you continue. The Factory saves Tasks to your organization.

3. Install skills and hooks

Run this from inside the repository:

cd path/to/your-repo
archdev setup --scope repository

Use --scope user to install for every repository on this machine instead.

What happens:

1. You're told that agent activity is reported to your organization's stream.
2. The archdev skill is installed for your coding agents.
3. Session hooks are installed for every coding agent it detects (Claude Code, Codex, Gemini and others). Add --all-harnesses to install for all of them.
4. With --scope repository, archdev.json is created at the repository root if it doesn't exist. If it exists, its activity block is added or normalized.

It ends with ArchDev setup is complete for <path>. This step doesn't connect models or install the daemon; steps 4 and 5 do that.

Next, install the planning skills so your coding agent can write and run Task plans:

archdev setup --skills --skill tasks plan-collab --scope repository

tasks turns a plan into Tasks and opens the browser review; tasks-execute is installed along with it. plan-collab lets you co-edit a plan with an agent in the browser.

Then: restart your coding agent so it loads the hooks.

4. Connect model access

The overseer and workers need models. Choose one or more of the options below. If you connect several, the Factory falls back to the next one when one is unavailable.

B. ChatGPT subscription

archdev settings provider login openai

What happens:

1. It prints Starting OpenAI ChatGPT OAuth (browser). Use --device-code over SSH., then Open: <url>, and opens the sign-in page.
2. You sign in with your ChatGPT account. The page redirects to localhost:1455.
3. It prints Logged in to OpenAI/ChatGPT OAuth (<profile>).

The browser has 5 minutes to finish. Over SSH the redirect can't reach your machine; use device code instead:

archdev settings provider login openai --device-code

It prints a URL (https://auth.openai.com/codex/device) and a code. Open the URL on any device and enter the code within 15 minutes.

C. SuperGrok / X Premium subscription

archdev settings provider login xai

xAI always uses device code. Open the printed URL, enter the code, and wait for Logged in to xAI OAuth (<profile>).

More than one subscription account

Several ChatGPT or Grok accounts let workers keep going when one account reaches its usage limit. Save the emails first, then log in to all of them:

archdev settings provider accounts openai add you@example.com
archdev settings provider accounts openai add you+2@example.com
archdev settings provider login openai

Login goes through the saved emails in order. It prints Sign in as <email>. for the first and Sign in as <email>, then press Enter. for each one after; sign out in the browser and sign in as that account. To log in to one account only, add --account <email>.

How the accounts are used: requests go to the first available account. When an account reaches its usage limit, it is benched until the reset time the provider gives (1 hour if none is given), and the next account takes over. If every account is benched, requests move to the next model in your factory.model / factory.worker_model list until an account comes back. ArchDev doesn't switch to an API key on its own, so list a second provider if you want work to continue.

D. Anthropic API key

archdev settings provider login claude --api-key sk-ant-...

Prints Stored claude API key (<masked>). Claude in ArchDev uses an API key only; browser login isn't supported. The ANTHROPIC_API_KEY, OPENAI_API_KEY and XAI_API_KEY environment variables also work.

E. Claude Code subscription for workers

Workers can run your local Claude Code (with its own login and plan) in tmux panes instead of ArchDev's built-in agent:

1. Install tmux and Claude Code, then run claude login.

2. Add this to archdev.json:

   CodeCopy code

   { "factory": { "worker_harness": "claude" } }
   

The overseer still uses option A, B, C or D. Claude Code workers use Claude Code's default model; factory.worker_model doesn't apply to them.

Validate and pick the default model

archdev agents setup

Run it from the repository root. What happens: if factory.model isn't set, a wizard asks for a provider:

1. ArchDev Model Router (requires payment)
2. OpenAI — your OpenAI account
3. xAI — your xAI account
Provider [1]:

The default is 1 (the paid Router). Pressing Enter, or running without a terminal, chooses it. To use a subscription, type 2 or 3. It asks for the account email and logs in again.

It then checks that at least one overseer model and one worker model are available, writes factory.model to archdev.json if it was missing (openai/gpt-6-sol for OpenAI, xai/grok-4.7 for xAI), and prints Agent setup is complete for <path>. Model: <ids>. To skip the wizard, run archdev agents setup --provider openai --provider-email you@example.com.

Check:

archdev settings provider list             # every provider: logged in? benched accounts?
archdev settings provider accounts openai  # each saved email: stored / not logged in
archdev settings provider usage            # ChatGPT/Grok plan, window, % used, reset time

Credentials are saved in ~/.archdev/credentials/model-providers.json (mode 0600). They're never written to the repository.

Choose models (optional)

List model IDs with archdev settings provider models <platform|openai|xai|claude>, then set them in archdev.json:

{
  "factory": {
    "model": ["openai/gpt-6-astra", "platform/xai/grok-latest-thinking-high"],
    "worker_model": ["openai/gpt-6-astra", "platform/xai/grok-latest-thinking-high"],
    "workers": 3
  }
}

• model is the overseer. worker_model is the workers; without it, workers use the overseer's model.
• A list is a fallback order. Candidates that aren't logged in, or that fail, are skipped.
• To use different models from your teammates, put the same keys in ~/.archdev/archdev.json. For model keys, your personal file overrides the repository's.

5. Install the daemon

archdev jobs runner install

What happens: it registers a per-user service that starts at login and restarts if it crashes, then prints ArchDev daemon installed.

The service saves your current PATH (absolute entries only), and no other environment variables. Run this command from a shell where git, gh and your toolchains are on the PATH, and run it again after you change them. If gh depends on an environment variable such as GH_TOKEN, sign in with gh auth login instead, so the daemon can open pull requests.

Check:

archdev jobs runner status

FIELD       VALUE
state       running
pid         12345
...

If state is stopped, run archdev jobs runner start. If it's not-installed or still fails, run archdev jobs runner doctor (see Troubleshooting). Logs are in ~/.archdev/logs/daemon.log.

6. Register the repository

From the repository root:

archdev jobs setup

What happens:

1. It asks which pull requests the daemon should follow up on:

   CodeCopy code

   1. Factory-created only (recommended; requires local creation history)
   2. All open pull requests authored by you
   PR tracking scope [1]:
   

   Your choice is saved as a personal setting in ~/.archdev/archdev.json, not in the repository. Pass --pr-tracking-scope factory-only or all-authored to skip the question.

2. If the daemon isn't installed, it offers to install it.

3. It creates your private ArchDev remote at ~/.archdev/repos/<name>.git, adds a git remote named archdev, and adds factory.model and publish.model to archdev.json if they're missing.

4. It prints:

   CodeCopy code

   ✓ Project identity configured at <path>/archdev.json.
   Private repo: ~/.archdev/repos/<name>.git
   Push with: archdev push
   

The private remote is local to your machine. The Factory pushes there first so the daemon can verify each commit before anything reaches GitHub.

If another checkout already uses that name, run archdev jobs setup --name <unique-name>.

7. Commit archdev.json to main

The Factory reads archdev.json as committed, and workers start from origin/main. Merge it before your first run:

git add archdev.json
git commit -m "Configure ArchDev"
# open and merge a PR, or push to main if your team allows it

Uncommitted changes to archdev.json produce a warning at startup and are ignored.

8. Verify everything

archdev check          # validates archdev.json; runs nothing
archdev repo status    # CLI, login, model access, repo wiring, hooks
archdev jobs runner status

You're ready when:

• archdev check prints ✓ ArchDev configuration is valid.
• archdev repo status shows ok for archdev_login and model_access.
• git remote -v lists an archdev remote (proves step 6 ran; repo_initialized only checks that archdev.json exists).
• archdev jobs runner status shows state running.
• gh auth status shows the account that will open pull requests.

Next: Plan work as Tasks.

Use a custom verification pipeline

By default, the daemon runs the built-in branch-validation pipeline on each Task's commit:

1. archdev inspect workflows run --target branch-commits: review the new commits.
2. archdev agents run …: fix the findings it can back up.
3. Commit the fixes.
4. Publish: open the pull request (publish.auto is on by default for this pipeline).

To run your own lint or tests first, define a pipeline and bind it:

{
  "pipelines": {
    "verify": {
      "steps": [
        { "id": "test", "run": ["make", "test"] },
        { "id": "review", "run": ["archdev", "inspect", "workflows", "run", "--target", "branch-commits"] }
      ]
    }
  },
  "pipeline_bindings": { "branch_update": "verify" },
  "publish": { "auto": true }
}

To open pull requests against a base branch other than main, drop publish.auto and end the pipeline with { "id": "publish", "run": ["archdev", "publish", "--base", "develop"] }. Automatic publishing only supports the origin remote.

Without publish.auto: true or an archdev publish step, no pull requests are opened. The Factory warns about this at startup: Factory tasks will not open pull requests…. Run archdev check after editing, then commit.