How to use Agent On Rails

What you need to set up

Already have aor? You mainly need a project contract, a coding agent, and a human approver. Agent On Rails does not replace Cursor / Claude / Codex — it packages the work for them.

1. 1. Python 3.11+ + git + aor — if aor guide works, CLI is done.
2. 2. Project contract — aor init ./my-product --name "My Product" (docs+specs only).
3. 3. Coding agent — Cursor, Claude Code, Codex, Gemini, or your Teknopus agent runner.
4. 4. Human gates — approve specs and final-review; evidence before done.
5. Optional — aor team, GitHub gh, API keys on the coding agent (not in git).

Full setup checklist on GitHub →

Setup app (macOS, Windows, Linux)

Prefer a wizard? The desktop setup app checks Python, installs the aor CLI, bootstraps your first docs+specs project, and can draft SurveyDesk-shaped specs from natural language (aor gather, confirm before write) — then hands off to the terminal UI. Onboarding only (ADR-008); day-to-day work stays in aor.

Agent On Rails 0.1.5 · 13 September 2026

macOS builds are signed with Developer ID. Open the DMG and drag Agent On Rails into Applications (app on the left, Applications folder on the right). Sparkle auto-update via appcast.xml; in the app use Agent On Rails → Check for Updates…. Windows MSI is published from GitHub Actions (unsigned until a code-signing certificate is configured). Requires Python 3.11+.

# Debian/Ubuntu system deps
sudo apt update
sudo apt install -y curl build-essential pkg-config \
  libwebkit2gtk-4.1-dev libayatana-appindicator3-dev \
  librsvg2-dev patchelf libssl-dev

# Build the setup wizard
git clone https://github.com/agent-on-rails/agent-on-rails-desktop.git
cd agent-on-rails-desktop
npm install
npm run tauri build
# → src-tauri/target/release/bundle/

Linux / server (agent host)

Lightest path for a Linux laptop or agent machine (Python CLI only — no desktop GUI). Same harness as Hermes-style workflows: approve a spec, package a bounded task, let your coding agent implement.

sudo apt install -y python3 python3-pip python3-venv git pipx   # Debian/Ubuntu
pipx ensurepath
pipx install git+https://github.com/agent-on-rails/agent-on-rails-cli.git
aor init ./my-product --name "My Product"
cd my-product && aor

Full Linux / server implementation steps →

Install the CLI

Works on macOS, Windows, and Linux. Requires Python 3.11+. Prefer pipx:

pipx install git+https://github.com/agent-on-rails/agent-on-rails-cli.git
aor

aor opens a mouse-friendly terminal UI (same idea as OpenCode, Claude Code, or Gemini). It is a harness — not a coding agent. Subcommands still work for scripts.

Or: curl -fsSL https://raw.githubusercontent.com/agent-on-rails/agent-on-rails-cli/main/scripts/install.sh | bash

Escalation, watchdog & unattended runtime

Approved contracts AOR-006 and AOR-009 define how Agent On Rails decides retries, stops forever-loops, and fails fast on environment hangs — without babysitting the terminal.

• Intelligent escalation (Option A) — distinct bugs across fix↔review are normal progress. The same failure signature climbs tier 1 → 2 → 3 → human. Strike max is only a safety ceiling.
• Environment ≠ smarter model — hung Gradle, npm, or a missing device is cancelled, notified, and marked blocked_environment. Independent work continues. Wave-level HUMAN_REQUIRED only when blocking acceptance remains.
• Run report — every wave ends with a durable report: spec_id, terminal_status, completed, blocked environment, skipped deps, coding failures, human actions, notifications. The engine authors it; empty lists are allowed, omitted keys are not.
• Task API — register with POST /v1/tasks, then run. The engine owns attempt, tier, and signature history — callers report events.
• Watchdog classification — specific-first: ./gradlew test is a test, build / assemble* is a build — not a short device timeout by default.

Escalation policy → Execution watchdog → Phase 1 coherence plan →

Walkthrough — start to final review

Full path: install → init → write spec → human approve → plan → run → coding agent implements → evidence → human final review.

1. 1. Install & open TUI — use the setup app or pipx install …, then aor.
2. 2. Init — create the docs+specs contract (no app code).
3. 3. New spec — edit spec.md, acceptance, and evidence while status is DRAFT.
4. 4. Approve — human gate. Agents cannot skip this.
5. 5. Plan + Run — packages .aor/packages/TASK-00N/prompt.md for Cursor / Claude / Codex.
6. 6. Implement — in the sibling app repo only. PR + tests = evidence.
7. 7. Final review — human Review in the TUI (or aor review TASK-001 --approve). Ready when evidence exists.

Open the full walkthrough on GitHub →