Ortus

Ortus (Latin: "rising, origin, birth") — the point from which something springs into being.

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

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

# Install Ortus globally (system-wide — don't add ortus as a project dependency)
curl -fsSL https://github.com/who/ortus/releases/latest/download/install.sh | sh

# 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

Note: Ortus is a global CLI you install once and use everywhere. You don't clone this repository into your project — ortus init only adds a small set of per-project files (.beads/, AGENTS.md, .ortusrc, .gitignore, and the selected backend's config directory) to an existing directory. It is not a Python dependency.

The eight verbs

Run ortus <verb> --help for flags. Run ortus --version for the installed version.

Supported platforms

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.

Prerequisites

Optional: CodeGraph. If .codegraph/ exists in a project, ortus grind's prompts use it for faster symbol/caller/callee lookups; otherwise the loop falls back to grep + Read.

Agent backends

Claude remains the default. Select Codex at project creation with ortus init . --backend codex, per run with --backend codex, or through ORTUS_BACKEND=codex. Precedence is command-line flag, environment, .ortusrc, then the Claude default.

Claude workers run a narrow claude -p '/goal …' session. Codex workers run the same logical single-issue task as a plain codex exec '…' prompt. Codex slash commands belong to its interactive UI; Ortus does not pass a literal /goal to codex exec. In both cases the outer ortus grind scheduler trusts only observable bd state and starts a fresh process for the next issue.

Why ortus

• One install, all projects. uv tool install ortus once; every repo uses the same canonical tooling. No more copier update chasing N repos.
• 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; Codex workers retain workspace-write, while Claude uses its generated sandbox policy.

Configuration

Optional <repo>/.ortusrc (TOML) overrides ~/.ortusrc:

prefix = "myproj"       # bd issue-id prefix
project_type = "python" # python | typescript | go | rust | polyglot
backend = "claude"      # claude | codex

Per-repo or user-wide prompt overrides live at <repo>/.ortus/prompts/<name>.md or ~/.ortus/prompts/<name>.md; the bundled defaults under src/ortus/prompts/ are the fallback (FR-025).

Session-close protocol

When ending a work session, push your work:

bd close <id> --reason "..."
git add -A && git commit -m "..."
bd dolt push
git push

Work is not done until pushed. The generated AGENTS.md repeats this in every project.

Development

# Local editable install
uv pip install -e '.[dev]'

# Tests
pytest                              # unit + integration (fast)
pytest -m smoke                     # end-to-end smoke
pytest --slow                       # everything, including real-claude smoke

License

MIT