English | 简体中文

Orbi

Orbi is a local AI development Worker: put work in a GitHub Issue, and it automatically claims the Issue, starts Pi in an isolated worktree to develop and test it, creates a PR, and then passes it through independent review and merge gates. GitHub Issues and labels are the only state store—there is no database, queue, or daemon.

• Website https://orbi.build ｜ Documentation https://docs.orbi.build/ (the repository's docs/ is the single source of truth; the Chinese entry point is docs/zh/) ｜ Updates @xqliu
• Join the first group of contributors: if you are stuck on the environment, model integration, or workflow, we can help you run your first Issue. The problems you encounter become Issues to prioritize.

Why Orbi

• GitHub Issues are the task pool: the ai-ready label dispatches work, and the delivery record (comments, PRs, and CI) is complete by default, with no second task system;
• Fully automated: a user scheduler timer (systemd on Linux, launchd on macOS) triggers a tick every 5 minutes. Normal operation needs no status command, polling, or supervision;
• Independent review + merge gates: after a PR opens, an independent review session reviews it and fixes findings in the same session. Only the reviewed head can merge, and AI never merges or pushes protected branches;
• Fail fast: command errors fail immediately and leave the evidence in the logs. The Issue is marked ai-blocked for a human decision, with no silent fallback;
• Observable end to end: every journal log and GitHub progress comment carries the same run_id, so the complete timeline can be reconstructed with one grep.

Quick start

git clone https://github.com/orbi-build/orbi.git && cd orbi
uv tool install --force --reinstall --editable --python python3 .  # compatible system Python (>= 3.14, e.g. Fedora 43 / current Arch); older system Python (e.g. Ubuntu 24.04 ships 3.12): --python 3.14 so uv provisions it

Want just the CLI? Published on PyPI as orbi-cli (release 0.5.7, requires Python ≥ 3.14; the installed command stays orbi): uv tool install orbi-cli (on an older system Python, e.g. Ubuntu 24.04's 3.12, add --python 3.14 so uv provisions a compatible interpreter) or pip install orbi-cli inside an activated Python ≥ 3.14 environment; verify with orbi --version → orbi 0.5.7, uninstall with uv tool uninstall orbi-cli. To run Orbi itself, use the one-line installer at the top of Getting started — it creates the editable install Orbi's deployment drives.

Ready check (before setup)

• uv: uv --version; Pi and its provider: pi --version, then pi --print "reply with the single word: ok"
• GitHub CLI ≥ 2.94 (official repository — Ubuntu 24.04's package 2.45.0 is too old): run gh auth login once, then verify gh auth status
• Linux — systemd user session: systemctl --user status
• macOS — launchd GUI session: launchctl print gui/$(id -u) (not yet verified on real hardware; reports welcome)

Choose the mode in Getting started: bootstrap uses this checkout as repo_dir; External single-repo mode uses it as deploy_home and a foreign repository as repo_dir.

cp src/orbi/example_config.toml orbi.toml
orbi setup --config orbi.toml  # 4. run one-time setup (checks prior gh auth, labels, scheduler units (systemd/launchd), and checkout; idempotent)
PYTHONPATH=src python3 -m orbi.runner --config orbi.toml  # 5. manually run one tick (for initial verification; the timer schedules normal runs)
orbi doctor --config orbi.toml  # 6. verify deployment health

What it does

GitHub Issue (ai-ready)
  → Claim: create a feature branch + isolated worktree (from the frozen origin/main SHA)
  → Pi development: plan → implement → test → verify
  → Commit delivery (the Agent stops at the commit)
  → Runner closeout: sync the latest base, push, and create a PR (body includes Fixes #N)
  → Independent review (fixes in the same session) → merge gate → merge

• Each task gets its own run: the branch, worktree, logs, and PR are all associated with the same run_id; retries create a new run and preserve the old evidence unchanged;
• Failures are classified clearly: recoverable failures return to the same PR for continued fixes, while unrecoverable failures mark the Issue ai-blocked for a human;
• Supports orbi add for dispatching work, status for viewing the queue, session for following the Pi session, install-units for idempotently installing the scheduler units (systemd on Linux, launchd on macOS), and doctor for read-only diagnostics.

Documentation

Development and contribution

See the development contract in AGENTS.md, and Contributing for dispatching Issues, reporting bugs, and submitting PRs. Runtime code lives in the src/orbi/ package (Issue #168 src layout; the editable finder maps the entire package directory, so new modules need no reinstall). The checkout root has no orbi.py (to avoid shadowing the installed package); the direct-execution compatibility entry point is python3 -m orbi.cli, not the formal usage path.

License

This project is fair-code, released under the Sustainable Use License (v1.0). See the complete text in LICENSE.md at the repository root.

In practice:

• Run Orbi on your own repositories for free forever—for personal use and internal company use alike, at any scale. You can modify the code, self-host it, and run it across a thousand repositories without requesting authorization.
• You may share it, provided that it is free and used for non-commercial purposes.
• Commercial authorization is required only when you sell Orbi itself—for example, hosting it as a service for customers or embedding it in a paid product.

If you are unsure which side your use falls on, ask in Discussions; we will give you a clear answer.