ARC Pi

ARC Pi is a thin, opinionated Pi distribution centered on andysolomon/arc-orchestrator. It keeps upstream Pi as the interactive parent while adding an isolated configuration, an openai-codex/gpt-5.6-sol/high-thinking default, bounded ARC delegation, diagnostics, prompts, and policy guidance.

The parent delegates almost everything through arc_delegate using runner-routing-v4. Automatic delegation passes the current ARC Delegate worker phase values with no --backend/--route; Analyze stays local in the active parent. Every Explore, Research, or Plan call pauses before runner and session creation so the operator can approve automatic routing or select a valid read-only route; decline, cancel, and non-interactive use fail closed. Implement requires operator approval of the exact contract and one of nine canonical workload_class values. Verify uses review mode, and Deploy retains separate authorization. Explicit aliases pin one runner route with no inherited fallback. See orchestration and routes.

Task-scoped Markdown artifacts are explicit and opt-in. Supply a lowercase single-segment task_slug on arc_delegate. Capable Explore, Research, and Plan workers receive it in runner argv and may author docs/<task_slug>/<phase>.md; ARC Pi snapshots before launch, restores non-completed outcomes, contains and sanitizes completed output, then appends harness evidence as an audit footer. Implement and Verify remain harness-written. Use the parent-local arc_task_artifact tool for Analyze or a manual phase summary. Calls without task_slug write nothing, and Deploy never creates an artifact. Automatic writes require parsed worker evidence with status exactly completed; all other statuses, malformed output, and opted-in cancellation fail closed without a success artifact. Cancellation restores prior artifact content or removes a cancelled first write. Artifact I/O errors are surfaced separately and do not rewrite a successful worker session as failed. Older runners that reject the flag are retried once without it with a warning and harness-only evidence.

Quick start

Prerequisites: Node.js 22.19+, Bun 1.2+, Pi 0.80+, and the backend CLIs required by the routes you use.

npm install --global @andysolomon/arc-pi@latest
arc-pi
# Run /login once inside ARC Pi's isolated configuration.

The first launch creates or updates the isolated ~/.arc-pi profile. npm installs the exact tested ARC runner automatically; no Git checkout or --runner path is required. Update both ARC Pi and its tested runner with:

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

For checkout development, run npm install, npm run verify, and optionally select a checkout runner with ./bin/arc-pi setup --runner /path/to/runner.

Inside Pi, use arc_delegate, arc_task_artifact, /arc-doctor, /arc-runs, /arc-report, /arc-monitor, /arc-terminals, /subagents, /orchestrate, or /skill:arc-orchestrator. /arc-report prints a Stage | Model | Result table for registered runs in the current session, or falls back to arc-orchestrator report when none exist. The model can call arc_monitor_status for a snapshot, use the separate arc_terminal_* tools for non-interactive dev servers, watchers, long tests/builds, and benchmarks, and use subagent_* for explicitly parallel, self-contained child tasks. ARC Pi ships and selects the github-dark-default theme for its isolated profile.

Background terminals live only for the current Pi session. arc_terminal_start returns promptly with an arc-term-… ID; arc_terminal_status, arc_terminal_list, and arc_terminal_kill inspect or stop it. /arc-terminals lists jobs, /arc-terminals <id> shows bounded output detail, and /arc-terminals kill <id> terminates the process tree. Completion queues one follow-up. Output tails stay bounded while full stdout/stderr use private, size-capped temporary spill files that are removed at session shutdown or history eviction. Terminals are Unix-only and always reap their process group. These terminals are local shell processes, not ARC model-worker jobs, and never resume with a session.

Parallel subagents also live only for the current Pi session. subagent_spawn returns immediately with an arc-sub-… ID and permits at most four active children. Use it only for disjoint, self-contained story or worktree tasks with clear boundaries; each child is an isolated in-process Pi session with its own cwd/model context, an explicit built-in tool allowlist, and no extension resources or tools. A successful, non-cancelled subagent_wait claims and returns all requested bounded results; a cancelled wait leaves the automatic completion follow-up available. subagent_check, subagent_list, and subagent_cancel inspect or stop children. Unclaimed completions queue one bounded follow-up. In TUI mode, /subagents and its /sub alias open a selectable dashboard; choosing a child opens a bounded live activity view where an operator can steer or abort an active child. Settled children remain viewable but read-only. Takeover uses s to steer and x to abort; thinking activity is shown separately from transcript and tool updates. Non-TUI commands retain bounded list/detail output. Children cannot call nested subagents, ARC delegation/background-terminal tools, decision/ask-user tools, or extensions, and active children are cancelled at parent-session shutdown. This is a resource/tool boundary, not an OS sandbox: the allowlisted local bash tool executes on the trusted host, and prompt restrictions are policy rather than operating-system enforcement. Subagents do not replace ARC phase routing or its authorization gates, and they cannot reattach across sessions.

Operators and outer agents can monitor sessions from a shell:

./bin/arc-pi-monitor status --session-id <id>
./bin/arc-pi monitor watch --session-id <id> --json

Delegation viewer

The delegation viewer is a second-terminal live view of orchestrator delegation: keep the parent Pi TUI in one pane and run the viewer beside it. It renders the lifecycle DAG (explore → analyze → plan → implement → verify → deploy), the background-job lane, the routing rungs actually walked per phase, and a scrubbable timeline — all from the same privacy-safe snapshots the parent TUI already shows.

It is a small Rust/ratatui binary in tui/, built separately from the npm package:

cargo install --path tui           # or: cd tui && cargo build --release

arc-pi monitor tui resolves the binary from ARC_PI_MONITOR_TUI, then the in-repo tui/target/{release,debug} build, then arc-pi-monitor-tui on PATH, and fails with build instructions if none exists.

./bin/arc-pi monitor tui --session-id <id>   # watch one session
./bin/arc-pi monitor tui --follow            # newest session; reattaches after idle
ARC_PI_SESSION_ID=<id> arc-pi-monitor-tui    # session inferred from the environment

Useful flags: --theme <path> loads any Pi theme JSON (github-dark-default and steel are built in), --interval-ms sets the monitor poll interval, --arc-pi-home points --follow at another registry root, and --stdin reads watch --json NDJSON instead of spawning the monitor — which also gives you an offline demo:

arc-pi-monitor-tui --stdin < tui/fixtures/live.ndjson      # full lifecycle to completion
arc-pi-monitor-tui --stdin < tui/fixtures/blocked.ndjson   # terminal verify failure

Reading the viewer

Each node is one delegated run for a lifecycle phase. analyze always renders as a parent node, never a worker. Under the status row are that phase's routing rungs from ARC Delegate v4: ✓ produced the result, ✗ advanced past for an availability reason, ● currently active, ◇ never reached. A verify failure is terminal — it draws a red fail → terminal edge into a blocked revise-contract node and dims the deploy gate, never a silent retry edge. Opt-in arc-bg-… jobs get their own right-hand lane.

The inspector tabs are Steps, Activity, Files, Diffs, Contract, Routing, and Info. Contract shows bounded registry metadata (label, phase, route, workload class, tokens) — raw task text, absolute paths, and transcripts are never sent to the viewer, and redacted or omitted diffs show a count or reason instead of content.

Keys

Key	Action	Key	Action
q	quit	Space	play / pause replay
Tab / 1–7	inspector tabs	← →	previous / next event
↑ ↓	focus a node	Home	first event
l	jump back to live	f	toggle follow
− +	playback speed	;	cycle theme
z	density	PgUp PgDn	scroll the graph
[ ]	scroll the inspector

With Herdr

Herdr manages agent terminals as workspaces, tabs, and panes, which makes it the natural home for a viewer pane next to the parent session (verified against herdr 0.8.0). From the pane running ARC Pi, split beside it and start the viewer without moving your focus:

pane=$(herdr pane split --current --direction right --cwd "$PWD" --no-focus \
  | jq -r .result.pane.pane_id)
herdr pane rename "$pane" arc-viewer
herdr pane run "$pane" ./bin/arc-pi monitor tui --follow

Split right from a wide pane and down from a narrow one. --follow is the right mode here: the viewer attaches to the newest session in the run registry and reattaches on its own after the monitor stops on idle, so the pane keeps working across successive delegations without being restarted.

Inside a Herdr-managed pane the session is already in the environment, so arc-pi-monitor-tui on its own picks up ARC_PI_SESSION_ID when ARC Pi exported it. To pin the viewer to one specific session instead of following the newest, pass --session-id explicitly.

Authenticate optional subscription-backed workers through their official CLIs:

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

These commands do not add Cursor or Claude Code to Pi's /login or /model menus. ARC Pi does not fork Pi core, copy provider credentials, or bundle provider CLIs. Its npm package installs one exact tested ARC runner dependency. Worker output remains advisory until the parent inspects changes and reruns focused verification.

Documentation

• Setup and configuration
• Architecture
• Orchestration and routes
• ARC Delegate model matrix
• Security model
• Development
• Extension evals
• ADR 0006 — Session monitor library-first
• ADR 0007 — Delegation viewer reads persisted live snapshots