Commands

Every command takes --json. In JSON mode, diagnostics go to stderr and stdout carries only the result. Configuration lives in the consuming repo's .repo-ai.json: agentUser and requiredSkills. doctor reports it missing; fix config creates it.

Setup

Command	What it does
setup [--yes] [--json]	Onboard a repo: runs fix config, fix claude-skills, fix allow-rules and fix statusline, asking before each. With an agent user, it prints the GH_TOKEN launch line instead of running the deprecated fix ai-loop-identity. It also creates or repairs the loop labels without asking and reports them in one line. Then it runs doctor.
doctor [--json]	Audit the loop setup: the loop labels against their spec; .repo-ai.json present and valid against its schema; agentUser matches the gh identity; humanUser set on an organisation-owned repo; autoMerge only with a release gate; CI runs — default-branch push runs cancelled or pending with no jobs, or a ciWorkflow that does not exist; Release approval — a release run waiting on approval for over a day; Release run — the newest completed default-branch run whose release job failed. Both read release.yml's runs (any event) when the repo has one, else the CI workflow's push runs; Security alerts — open Dependabot alerts, high/critical named and moderate/low folded into the count, silent on 403/404; installed skills, plugin skills and workflows, and whether they are current; requiredSkills installed; the Claude Code permissions.allow rules a tick needs; with Claude Code's sandbox on, gh * and npx @infrazero/repo-ai * in sandbox.excludedCommands; whether your statusline shows the loop status; and that agents have checks to run before pushing — a checkCommand, or a CLAUDE.md or AGENTS.md. requiredSkills, permissions and the sandbox are checked only when agentUser is set. All read-only. Exits 1 only on drift / missing.
auth app-token --repo <owner/repo> [--json]	Print an installation token for the loop's GitHub App, scoped to one repo, from GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY_FILE (or GITHUB_APP_PRIVATE_KEY). GH_TOKEN=$(npx @infrazero/repo-ai auth app-token --repo o/r) puts gh and git on the App's identity for an hour. An installation token cannot call GET /user, so set REPO_AI_GH_LOGIN=<slug>[bot] (the --json login) alongside it.
dashboard [--port 8080] [--data /data] [--repos /repos]	The Docker api service: the one scheduler (tick → apply → queue), the worker queue, and the JSON the dashboard app draws. See Run in Docker.
worker [--url http://dashboard:8080] [--id <hostname>]	A Docker agent worker: pulls a task from the dashboard, runs it with headless Claude Code, reports back.
fix config	Write $schema, and every unset key that has a default, into .repo-ai.json. With no file, create one, migrating any old .repo-tooling.json settings once.
fix labels	Repair loop label colours and descriptions with gh label edit.
fix claude-skills	Install or update the skills into ~/.claude/skills (or --skills-dir <path>), and the Workflow scripts they run by name into the sibling workflows/ directory. --force-skills overwrites a modified or newer copy.
fix ai-loop-identity	Deprecated (#285): point this checkout's Claude sessions at a gh profile signed in as agentUser. Prefer a per-session GH_TOKEN.
fix repo-settings	Set the GitHub settings the loop needs, and nothing else: squash as the only merge method, auto-merge allowed, delete branch on merge, and no required pull request reviews (one identity can't approve its own PRs, so a required review deadlocks every PR). Keeps every required status check the default branch already has and never removes a rule. With none, it offers the check names from the default branch's last CI run; under --yes it requires none and says so. Never adds a ruleset or CodeQL. Shows the plan and asks before writing; --yes applies it. Needs a repo admin.
fix allow-rules	Add the loop's missing Claude Code allow rules to this checkout's gitignored .claude/settings.local.json: Bash(gh:*), Bash(git *), Bash(npx @infrazero/repo-ai *), and Bash(<pm>:*) for the package manager its lockfile names. It also adds permissions.deny rules for the escapes those open: git -c, git config, git --config-env, git --exec-path, and the package manager's dlx/exec/x/create/init. Appends only, and refuses to write through a symlinked .claude or settings file. Writes nothing when another settings file already grants them, or a bare Bash allows everything.
fix sandbox	With Claude Code's sandbox on, add gh * and npx @infrazero/repo-ai * to sandbox.excludedCommands in the settings file that turns it on. An allow rule only skips the prompt; a sandboxed gh fails TLS on macOS (no keychain) and npx can't write its cache, so a tick halts or needs an unsandboxed retry the auto-mode classifier may refuse. Excluding gh * gives gh your keychain and network, which the loop needs anyway to label PRs. Never sets enabled, never creates a sandbox block, and writes nothing while the sandbox is off. Chained calls (cd x && gh …) still run sandboxed.
fix statusline	Install the loop's status segment (🤖 2 agents·1 to merge · next 9m) to ~/.claude/ai-loop-statusline.sh, replacing that file on every run (it is ours; don't edit it). Never touches an existing statusline: sets statusLine in ~/.claude/settings.json only when you have none, otherwise prints the one line to add to your own script. Never prompts.

Moving over from repo-tooling? Skills installed by @rtorcato/repo-tooling carry that package's version stamp, so fix claude-skills treats them as local edits and won't overwrite them. Run it once with --force-skills.

Loop mechanics

The skills call these; you rarely need them directly.

Command	What it does
loop tick	Compute one tick's whole work list (guard, cleanup, reap, verdicts, pickups). .skippedPickups[] names each ai-ready issue it passed over and why (an untrusted author, or a file an ai-wip issue also names); .dependabotRecreate lists the red or DIRTY Dependabot PRs in the loop that loop apply asks to @dependabot recreate. Read-only: writes no GitHub state and removes no worktree — loop apply does that.
loop watch	Poll loop tick's work list every pollSeconds and print a line only when it changes: HH:MM <summary> review #78 · pickup #39 …. An agentUser mismatch warns on stderr instead of halting. Runs until killed.
loop guard	Repair a wrongly-bare main checkout, gate the node_modules rebuild, and assert the agent identity.
loop env	Print a tick's values (root, worktree root, owner/repo, agent and human users) for a human; the skill reads them from loop tick --json.
loop worktree add <slug>	Create an ai-* worktree off origin/main and link its dependencies.
loop cleanup	Remove ai-* worktrees whose PR has landed or closed.
loop apply	Apply a tick's deterministic writes: Pass 1's disarm, handoff, send-back, merge-ready strip and branch update; Pass 2's worktree removal (then the node_modules rebuild gate), ai-wip relabel and the label side of each stall. Its only merge is an autoMerge handoff. Each label edit is preceded by an upserted transition comment naming the agent (REPO_AI_AGENT) and the next owner (#332). Reports every edit, and in comments each comment the caller still owes.
loop reap	Report agents stalled past 45 minutes and what to do about each.
loop comment <pr>	Upsert the loop's one decision-marker comment on a PR.
loop verdict <pr>	Read a reviewer's verdict marker for the PR's current head.
loop tier <pr>	Choose the review tier from the PR's changed paths: both (docs-only — one combined reviewer) or split (code + sec). Fails closed to split.

Skills

Skill	Role
/ai-loop	Start here. Implements the ai-ready queue in parallel worktrees, then keeps itself going in this session, carrying the PRs through review, fix rounds and cleanup. Type it again to tick now.
/ai-issue	File an issue labelled ai-ready for the loop to pick up.
/ai-loop-status	Read-only: what the loop is doing, and what is blocked.
/ai-loop-stop	Stop this repo's loop in this session: its recurring job and loop watch watcher. Lists in-flight claims; never removes them.