# Setup and Configuration

## Prerequisites

- macOS or Linux;
- Node.js 22.19 or newer;
- Bun 1.2 or newer for the packaged ARC runner;
- Pi 0.80 or newer installed; authenticate `openai-codex` (for the default `gpt-5.6-sol` parent) inside ARC Pi's isolated configuration;
- the backend CLIs required by the routes you intend to use.

ARC Pi does not install Pi, Bun, Codex, Cursor Agent, or Claude Code. Pi provider authentication remains under `/login`; ARC Pi can initiate vendor-owned Cursor Agent and Claude Code authentication as described below.

## npm installation

```sh
npm install --global @andysolomon/arc-pi@latest
arc-pi
```

npm installs the exact tested `@andysolomon/arc-orchestrator` dependency. The first `arc-pi` launch creates the isolated profile; later launches rerun setup only when the ARC Pi package version or installation root changes. Setup never runs as an npm lifecycle script and npm installation does not write to the operator's home.

Existing saved checkout runners remain authoritative. To deliberately migrate one to the installed dependency, run:

```sh
arc-pi setup --bundled-runner
```

Reverse that choice at any time with `arc-pi setup --runner /absolute/path/to/runner`. Environment variable `ARC_ORCHESTRATOR_BIN` remains the highest-priority per-launch override.

## Local development installation

```sh
git clone <this-repository-url> arc-pi
cd arc-pi
npm install
npm run verify
```

Configure the external runner:

```sh
./bin/arc-pi setup \
  --runner /absolute/path/to/arc-orchestrator/plugins/arc-orchestrator/bin/arc-orchestrator
```

Setup is idempotent. It merges defaults and appends a marked policy block without replacing existing operator content.

Start ARC Pi and authenticate the isolated profile on first use:

```sh
./bin/arc-pi
```

```text
/login
```

ARC Pi intentionally does not reuse `~/.pi/agent` credentials because its `PI_CODING_AGENT_DIR` is isolated. Environment-based provider credentials remain available when exported before launch. Setup also provisions Pi model overrides that keep the supported OpenAI Codex GPT models at a 272K context window; existing operator overrides remain authoritative. The package ships and selects the `github-dark-default` theme unless an existing theme setting is already present.

A local checkout uses its installed npm runner dependency by default. Supplying `--runner` remains useful when developing the runner from a sibling checkout.

## Authenticate subscription-backed workers

Cursor Agent and Claude Code remain ARC worker backends, not Pi model providers. Their official CLIs own credentials in their normal user-level stores:

```text
/arc-login
```

With no argument, interactive ARC Pi asks which CLI to authenticate. Explicit selection is also available:

```text
/arc-login cursor
/arc-login claude-code
/arc-auth-status
/arc-auth-status cursor
/arc-auth-status claude-code
```

Login instructions are shown only in temporary UI and are cleared when the command finishes. Status output is limited to `missing`, `authenticated`, `unauthenticated`, or `unknown`; it omits email, subscription tier, token source, and raw provider output. Press Escape in the interactive login loader to cancel the child process.

ARC Pi does not provide logout because these credentials are shared with the normal vendor CLIs. Deliberate logout remains available through `cursor-agent logout` or `claude auth logout` in a shell. ARC Pi also never installs or updates either CLI. Use the official installation instructions when a CLI is missing:

- [Cursor Agent CLI installation](https://cursor.com/docs/cli/installation)
- [Claude Code setup](https://docs.anthropic.com/en/docs/claude-code/setup)

Pi's built-in Anthropic `/login` is separate from Claude Code CLI subscription authentication. ARC Pi does not copy a Claude Code token into Pi or claim that Pi-native Anthropic usage consumes Claude Code subscription limits.

## Verify the installation

Inside ARC Pi:

```text
/arc-doctor
```

From a shell after npm installation:

```sh
arc-orchestrator doctor
```

For checkout development, use `./bin/arc-orchestrator doctor`. Set `ARC_ORCHESTRATOR_BIN=/absolute/path/to/runner` to test an explicit runner.

The doctor should report the runner and intended backends as ready before live delegation.

## Session monitoring

Session health is library-first ([ADR 0006](adr/0006-session-monitor-library-first.md)): the orchestrator extension writes a per-session run registry; the monitor library and CLI only read.

Inside Pi:

```text
/arc-monitor
```

The model may call `arc_monitor_status` for a snapshot. There is no model-callable watch tool. Inside Pi the default session is the current session.

From a shell (session ref required):

```sh
./bin/arc-pi-monitor status --session-id <id>
./bin/arc-pi-monitor watch --session-id <id> --json
./bin/arc-pi monitor status --session-file ~/.arc-pi/sessions/.../<file>.jsonl
```

Pretty TTY is the default; `--json` emits machine-readable status or NDJSON watch ticks. `watch` exits when the session is idle (no runners and no session growth). Soft intervene surfaces `recommend_cancel` only — the CLI does not kill workers. Real cancel remains Pi abort / operator action.

Default token budgets: per-runner soft 1.5M / hard 3M; session soft 10M / hard 20M. Soft thresholds warn; hard thresholds may set `recommend_cancel`. Override with the `ARC_SESSION_MONITOR_*` or `ARC_PI_MONITOR_*` environment variables above.

### Long-running monitor loop

`bin/arc-monitor-loop` runs a campaign sampling loop (`node <campaign-dir>/sample-all.mjs` every interval until an end epoch) detached from the controlling terminal via `setsid -f`, so it survives parent shell exit. When `setsid` is unavailable it falls back to `nohup` with a warning. The loop appends to `<campaign-dir>/loop.log` and records its pid in `<campaign-dir>/loop.pid`. The wrapper resolves its `node` binary at startup — `$ARC_PI_NODE_BIN` if set, then `PATH`, then common install locations (`/usr/local/bin/node`, `/opt/homebrew/bin/node`, `/usr/bin/node`, and the highest-versioned `~/.nvm/versions/node/*/bin/node`) — and exits with a clear error naming `ARC_PI_NODE_BIN` if none match:

```sh
./bin/arc-monitor-loop --campaign-dir ~/.arc-pi/monitor-reports/v3 \
  --end-epoch "$(($(date +%s) + 86400))" --interval 900
```

For launchd-supervised runs, `bin/arc-monitor-loop-launchd` emits a LaunchAgent plist (`~/Library/LaunchAgents/com.arc-pi.monitor-loop.<label>.plist`) referencing the wrapper with `RunAtLoad=false` and `KeepAlive.SuccessfulExit=false`, so launchd restarts the loop after crashes but not after a clean end-epoch exit. The plist carries no `EnvironmentVariables`/`PATH` override — launchd's minimal default PATH is fine because the wrapper resolves `node` itself. It only writes the plist — nothing is loaded automatically. Start and stop it yourself:

```sh
./bin/arc-monitor-loop-launchd --label v3 \
  --campaign-dir ~/.arc-pi/monitor-reports/v3 \
  --end-epoch "$(($(date +%s) + 86400))" --interval 900
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.arc-pi.monitor-loop.v3.plist
launchctl kickstart gui/$(id -u)/com.arc-pi.monitor-loop.v3
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.arc-pi.monitor-loop.v3.plist
```

## Configuration locations

| Setting                | Default                          |
| ---------------------- | -------------------------------- |
| ARC Pi home            | `~/.arc-pi`                      |
| Pi agent directory     | ARC Pi home                      |
| Pi settings            | `~/.arc-pi/settings.json`        |
| Pi model overrides     | `~/.arc-pi/models.json`          |
| Parent policy          | `~/.arc-pi/AGENTS.md`            |
| Launcher config        | `~/.arc-pi/arc-pi-launcher.json` |
| Install/version marker | `~/.arc-pi/arc-pi-install.json`  |
| Session run registry   | `~/.arc-pi/session-runs/`        |
| ARC traces             | `~/.arc-orchestrator/traces/`    |

Set `ARC_PI_HOME` to relocate the ARC Pi home. Set `PI_CODING_AGENT_DIR` when Pi's agent files should live elsewhere.

## Environment variables

| Variable                                                                         | Purpose                                                                                   | Default                                                       |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `ARC_PI_HOME`                                                                    | ARC Pi state root                                                                         | `~/.arc-pi`                                                   |
| `PI_CODING_AGENT_DIR`                                                            | Pi configuration root                                                                     | `ARC_PI_HOME`                                                 |
| `PI_BIN`                                                                         | Pi executable used by launcher                                                            | `pi`                                                          |
| `ARC_PI_PROVIDER`                                                                | Parent provider                                                                           | `openai-codex`                                                |
| `ARC_PI_MODEL`                                                                   | Parent model                                                                              | `gpt-5.6-sol`                                                 |
| `ARC_PI_THINKING`                                                                | Parent thinking level                                                                     | `high`                                                        |
| `ARC_ORCHESTRATOR_BIN`                                                           | Explicit external ARC runner                                                              | saved setup value, exact dependency, or development discovery |
| `ARC_PI_ARC_WRAPPER_BIN`                                                         | Testing/development override for the package wrapper                                      | package-local wrapper                                         |
| `ARC_PI_DELEGATE_TIMEOUT_MS`                                                     | Hard deadline for `arc_delegate` workers (SIGTERM, then SIGKILL)                          | `1800000` (30 minutes)                                        |
| `ARC_ORCHESTRATOR_CURSOR_BIN`                                                    | Cursor Agent executable used by both worker execution and ARC authentication              | `cursor-agent`                                                |
| `ARC_ORCHESTRATOR_CLAUDE_BIN`                                                    | Claude Code executable used by both worker execution and ARC authentication               | `claude`                                                      |
| `ARC_SESSION_MONITOR_RUNNER_SOFT_TOKENS` / `ARC_PI_MONITOR_RUNNER_SOFT_TOKENS`   | Per-runner soft token budget                                                              | `1500000`                                                     |
| `ARC_SESSION_MONITOR_RUNNER_HARD_TOKENS` / `ARC_PI_MONITOR_RUNNER_HARD_TOKENS`   | Per-runner hard token budget                                                              | `3000000`                                                     |
| `ARC_SESSION_MONITOR_SESSION_SOFT_TOKENS` / `ARC_PI_MONITOR_SESSION_SOFT_TOKENS` | Session soft token budget                                                                 | `10000000`                                                    |
| `ARC_SESSION_MONITOR_SESSION_HARD_TOKENS` / `ARC_PI_MONITOR_SESSION_HARD_TOKENS` | Session hard token budget                                                                 | `20000000`                                                    |
| `ARC_PI_MONITOR_TOKEN_FAILFAST`                                                  | Require completed runner evidence to include token accounting; set to `active` to enforce | off (unset/empty/unrecognized)                                |

Command-line `--provider`, `--model`, and `--thinking` values override launcher defaults. A provider-qualified model argument also suppresses the default provider argument.

The external runner supports additional `ARC_ORCHESTRATOR_*` and Laminar variables. See the runner repository for its authoritative configuration list.

## Updating

For npm installations, one command updates ARC Pi and installs the exact runner version tested by that ARC Pi release:

```sh
npm install --global @andysolomon/arc-pi@latest
```

The next launch refreshes only ARC Pi-managed profile content and preserves settings, model overrides, credentials, launcher overrides, AGENTS content outside the managed block, and session state.

For a local ARC Pi checkout:

```sh
git pull
npm install
npm run verify
```

A deliberately configured checkout runner remains independent of npm updates. ARC Pi stores that absolute runner path in `~/.arc-pi/arc-pi-launcher.json`:

```text
~/orchestrator/plugins/arc-orchestrator/bin/arc-orchestrator
```

Update that checkout independently:

```sh
cd ~/orchestrator
git pull
bun install
bun run validate
./plugins/arc-orchestrator/bin/arc-orchestrator doctor
```

No ARC Pi reinstall or setup rerun is needed after an in-place orchestrator update. Each new delegation starts the runner from that checkout, so it uses the updated orchestrator code automatically. Restart ARC Pi after updating when practical; already-running worker processes continue using the old code until they finish. Re-run ARC Pi setup only when the runner path changes or the checkout moves:

```sh
./bin/arc-pi setup \
  --runner /absolute/path/to/orchestrator/plugins/arc-orchestrator/bin/arc-orchestrator
```

Existing user settings remain authoritative. Do not install the separate `arc-orchestrator-pi` project package alongside ARC Pi; ARC Pi already provides the canonical skill, prompt, and extension. The launcher detects that legacy project package and ignores project-local Pi resources for that run to prevent collisions.

## Troubleshooting

- **Packaged runner requires Bun:** install Bun 1.2 or newer and ensure `bun` is on `PATH`.
- **`no ARC runner executable found`:** reinstall ARC Pi and its exact dependencies, rerun setup with an absolute executable path, or put a development runner on `PATH`.
- **Runner path is rejected:** confirm it exists and has execute permission (`chmod +x`).
- **Extension is missing:** inspect the absolute package entry in the isolated `settings.json`, confirm `extensions/arc-orchestrator/index.ts` exists, then restart Pi or use `/reload`.
- **Model unavailable:** authenticate Pi's `openai-codex` provider (default `gpt-5.6-sol`) or override the launcher model/provider.
- **Provider CLI missing:** install it from the vendor's official documentation or set the matching `ARC_ORCHESTRATOR_*_BIN` to the executable used by ARC workers.
- **Authentication unknown:** run the vendor's status command directly in a shell; ARC Pi intentionally does not expose unrecognized raw status output.
- **Backend unavailable:** run `/arc-doctor`; retry automatic `arc_delegate` (omit `route`) so the runner can walk its availability chain, or intentionally pin one of the 90 v4 aliases, such as `fable-explore`, `gpt-5.6-sol-implement`, `kimi-k3-check`, `glm-5.3-flash-explore`, or `composer-2.5-check`.
- **Delegation timed out:** `arc_delegate` kills the worker after `ARC_PI_DELEGATE_TIMEOUT_MS` (default 30 minutes). Raise the limit for long legitimate runs; if the worker nested another runner or is waiting on its own write lock, cancel and fix the contract instead.
- **Sol-first implementation:** automatic calls omit `route`, set
  `phase: implement`, and choose `workload_class: hard-medium` or `hard-light`.
  An intentional explicit pin may use `sol-implement` or
  `gpt-5.6-sol-implement`; `codex-*` remains invalid, and `task_class` never
  selects a model.
- **Normal Pi configuration changed:** verify `PI_CODING_AGENT_DIR`; ARC Pi should point at its isolated directory, not `~/.pi/agent`.