About this project

Orbi is an automated system that transforms GitHub Issues into tagged releases. It claims an Issue, develops it in an isolated worktree, runs an independent review session, merges only the reviewed head, and publishes a tag via a release Issue. GitHub Issues serve as the sole state store—no database, queue, or daemon. Key features: - **Task pool via GitHub Issues**: The `ai-ready` label dispatches work; delivery records (comments, PRs, CI) are complete by default. - **Fully automated**: A user scheduler timer (systemd on Linux, launchd on macOS) triggers a tick every 5 minutes; no manual status commands needed. - **Independent review + merge gates**: After a PR opens, an independent review session fixes findings; only the reviewed head can merge, and AI never merges or pushes protected branches. - **Fail fast**: Command errors fail immediately, log evidence, and mark the Issue `ai-blocked` for human decision. - **Observable end to end**: Every log and GitHub comment carries the same `run_id` for full timeline reconstruction. Workflow: GitHub Issue (ai-ready) → Claim (branch + worktree) → Pi development (plan, implement, test, verify) → Commit delivery → Runner closeout (sync, push, create PR) → Independent review → Merge gate → Merge. CLI commands include `orbi add` (dispatch work), `status` (view queue), `session` (follow Pi session), `install-units` (install scheduler units), and `doctor` (read-only diagnostics). Installation requires Python ≥ 3.14, `uv`, `pi` (with a provider), GitHub CLI ≥ 2.94, and a Linux systemd user session or macOS launchd GUI session. Quick start: clone, install with `uv tool install --force --reinstall --editable --python python3 .`, copy example config, run `orbi setup`, then `python3 -m orbi.runner` for a manual tick, and `orbi doctor` to verify health. Documentation covers getting started, setup, workflow, operations, testing, and contributing. The project is fair-code licensed under the Sustainable Use License (v1.0): free for personal and internal company use, shareable for non-commercial purposes, but commercial authorization required only if selling Orbi itself (e.g., hosting as a service).