Metadata-Version: 2.4
Name: orbi-cli
Version: 0.5.7
Summary: Orbi — local AI development worker: claims GitHub Issues, runs Pi in isolated worktrees, and delivers PRs (GitHub Issues + labels are the only state store).
Author: xqliu
License: # License
        
        Copyright 2026 xqliu
        
        Orbi is [fair-code](https://faircode.io) distributed under the **Sustainable Use
        License** (v1.0), reproduced in full below.
        
        ## What this means in practice
        
        - **Running Orbi on your own repositories is free, forever** — for yourself, and
          inside a company of any size. Modify it, self-host it, run it on a thousand
          repos; none of that needs a licence from us.
        - **You may share it**, as long as you do so free of charge and for
          non-commercial purposes.
        - **You need a commercial licence only if you sell Orbi itself** — hosting it as
          a service for your own customers, or embedding it in a product you charge for.
        
        If you are unsure which side of that line your use falls on, open a discussion at
        https://github.com/orbi-build/orbi/discussions and we will answer plainly.
        
        The summary above is a convenience, not a substitute. The licence text below is
        what governs.
        
        ## Sustainable Use License
        
        Version 1.0
        
        ### Acceptance
        
        By using the software, you agree to all of the terms and conditions below.
        
        ### Copyright License
        
        The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
        to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
        to the limitations below.
        
        ### Limitations
        
        You may use or modify the software only for your own internal business purposes or for non-commercial or
        personal use. You may distribute the software or provide it to others only if you do so free of charge for
        non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
        the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
        
        ### Patents
        
        The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
        license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
        subject to the limitations and conditions in this license. This license does not cover any patent claims that
        you cause to be infringed by modifications or additions to the software. If you or your company make any
        written claim that the software infringes or contributes to infringement of any patent, your patent license
        for the software granted under these terms ends immediately. If your company makes such a claim, your patent
        license ends immediately for work on behalf of your company.
        
        ### Notices
        
        You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
        terms. If you modify the software, you must include in any modified copies of the software a prominent notice
        stating that you have modified the software.
        
        ### No Other Rights
        
        These terms do not imply any licenses other than those expressly granted in these terms.
        
        ### Termination
        
        If you use the software in violation of these terms, such use is not licensed, and your license will
        automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
        violation of this license no later than 30 days after you receive that notice, your license will be reinstated
        retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
        terms will cause your license to terminate automatically and permanently.
        
        ### No Liability
        
        As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
        not be liable to you for any damages arising out of these terms or the use or nature of the software, under
        any kind of legal claim.
        
        ### Definitions
        
        The “licensor” is the entity offering these terms.
        
        The “software” is the software the licensor makes available under these terms, including any portion of it.
        
        “You” refers to the individual or entity agreeing to these terms.
        
        “Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
        all organizations that have control over, are under the control of, or are under common control with that
        organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
        management and policies by vote, contract, or otherwise. Control can be direct or indirect.
        
        “Your license” is the license granted to you for the software under these terms.
        
        “Use” means anything you do with the software requiring your license.
        
        “Trademark” means trademarks, service marks, and similar rights.
        
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE.md
Dynamic: license-file

English | [简体中文](README.zh-CN.md)

# 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/`](docs/) is the single source of truth; the Chinese entry point is [`docs/zh/`](docs/zh/)) ｜ Updates [@xqliu](https://x.com/xqliu)
- **[Join the first group of contributors](https://orbi.build/apply)**: 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

```bash
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`](https://pypi.org/project/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](docs/getting-started.mdx) — 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](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) — 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](docs/getting-started.mdx): bootstrap uses this checkout as `repo_dir`; [External single-repo mode](docs/getting-started.mdx#external-single-repo-mode-deploy_home) uses it as `deploy_home` and a foreign repository as `repo_dir`.

```bash
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

```text
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

| Topic | Entry point |
|---|---|
| Documentation home | <https://docs.orbi.build/> |
| Getting started (prerequisites, configuration, first run, smoke test) | [Getting started](docs/getting-started.mdx) |
| One-time setup (labels, units, transport migration) | [One-time setup](docs/setup.mdx) |
| Workflow (state chain, labels, P0, Epic, Release) | [Workflow](docs/workflow.mdx) |
| Operations (timer, journal, unit drift, recovery) | [Operations](docs/operations.mdx) |
| Testing, coverage gates, and remote CI | [Testing](docs/testing.mdx) |
| Contributing (Issue granularity, KISS/LEAN, PR flow) | [Contributing](docs/contributing.mdx) |
| Chinese documentation | [docs/zh/](docs/zh/) |

## Development and contribution

See the development contract in [AGENTS.md](AGENTS.md), and [Contributing](docs/contributing.mdx) 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](https://faircode.io), released under the **Sustainable Use License** (v1.0). See the complete text in [LICENSE.md](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](https://github.com/orbi-build/orbi/discussions); we will give you a clear answer.
