Ortus

Ortus (Latin: "rising, origin, birth"), the point from which something begins.

Ortus autonomously closes a backlog of bd-tracked issues using Claude Code, Codex, Grok, or a model you serve yourself, one fresh subprocess per task. Inspired by the Ralph Loop concept: fresh window per task, drive the queue to zero, no context drift.

How it works

Diagram source: docs/img/how-it-works.reladraw, rendered with reladraw docs/img/how-it-works.reladraw -o docs/img/how-it-works.svg.

Install

Requires uv on PATH. Ortus is distributed via PyPI and installed by uv; we don't auto-install uv.

One-liner (recommended):

curl -fsSL https://github.com/who/ortus/releases/latest/download/install.sh | sh

Direct PyPI:

uv tool install ortus
ortus --version

From source / pinned commit:

uv tool install git+https://github.com/who/ortus.git
# Pin a specific tag/branch:
uv tool install 'git+https://github.com/who/ortus.git@v0.1.0'

Troubleshooting:

Quick start

# Bootstrap YOUR project
cd your-project
ortus init .

# Verify prereqs for the configured backend
ortus check .

# Decompose a PRD into bd issues
ortus plan . path/to/feature.md

# Or run the idea→interview→PRD→tasks flow with no PRD path
ortus plan .

# Drive the bd queue to zero, one task per fresh agent subprocess
ortus grind .

# Override the project backend for one run
ortus grind . --backend codex

# Bounded: stop after N tasks
ortus grind . --tasks 5

# Prototype bar for one run: lint and syntax checks only, no behavioral tests
ortus grind . --prototype

Note: Ortus is a global CLI you install once and use everywhere, not a Python dependency. You don't clone this repository into your project. ortus init only adds a small set of per-project files to an existing directory, and host prose in AGENTS.md and CLAUDE.md outside the Ortus markers is left alone. See agent backends.

Prerequisites

Required: CodeGraph. ortus init installs the index and pins codegraph = "required", and plan/grind abort before launching an agent when it is missing. For a repository CodeGraph cannot index, bootstrap without it using ortus init --codegraph off. See the CodeGraph lifecycle.

Windows is not supported (decision 2026-05-17). Windows users should run ortus inside WSL2 (Windows Subsystem for Linux), where ortus runs as a normal Linux process.

The verbs

Seven more verbs — interview, human, unlock, spec, cost, eval and prompt — and every flag are in the command reference. Run ortus <verb> --help for flags, ortus --version for the installed version.

Why ortus

• One install, all projects. uv tool install ortus once; every repo uses the same canonical tooling. No per-repo vendor copies to chase.
• bd ready IS the queue. No README task lists, no TodoWrite scratchpads. The queue is data.
• The scheduler is the loop. Backend output is advisory; observable bd state decides whether an iteration succeeded, orphaned a claim, or made no change.
• Sandboxed by default. ortus grind refuses to launch unless bwrap/Seatbelt is available, and each backend gets the strongest posture it supports.

Configuration

An optional <repo>/.ortusrc (TOML) overrides ~/.ortusrc. Every key has a working default:

prefix = "myproj"       # bd issue-id prefix
project_type = "python" # python | typescript | go | rust | polyglot
backend = "claude"      # claude | codex | grok | opencode (older name: local)
codegraph = "required"  # off | auto | required
verification = "full"   # full | prototype
integration_branch = "main"

[profiles.claude.implement]
model = "sonnet"

The full key reference, per-phase profiles, and the prototype verification bar are in configuration.

Documentation

• Agent backends — choosing a backend, managed agent files, worker shape, sandbox posture
• Serving a local model — the opencode backend against a server you run
• Configuration — the full .ortusrc reference, profiles, verification bar
• The grind loop — readiness gate, how an iteration finishes, state graph, session-close
• Authoring work — plan, interview, ingest, validate, spec
• Command reference — every verb and subcommand with its key flags
• Cost and evaluation — per-bead billing buckets and the frozen evaluation set
• CodeGraph lifecycle — the three policies, the index, troubleshooting
• Runtime prompts — ortus prompt list/show/eject and resolution order
• Glossary — the vocabulary log lines and prompt contracts use
• Test gate — changed-path selection, verifier expansion, release smoke
• Label state machine — the interview/PRD label vocabulary
• ZFC rubric — zero-framework cognition, the design rule behind the loop

Development

uv sync --all-extras
uv run pytest -m fast -n auto --test-timeout=30
uv run pytest -m integration -n auto --test-timeout=60

See the test-gate guide for changed-path selection, verifier expansion, CI timing evidence, and tagged network/live-provider release smoke.

License

MIT