chippingway/chipping-orchestrator

**Autonomous GitHub issue → reviewed PR pipeline for Claude Code, Codex CLI, and Antigravity CLI.**
[![CI][ci-badge]][ci-link]
[![OpenSSF Scorecard][scorecard-badge]][scorecard-link]
[![OpenSSF Best Practices][best-practices-badge]][best-practices-link]
chipping-orchestrator turns GitHub issues into reviewed pull requests with local coding-agent CLIs (codex,
claude, or agy). It plans the work, implements it in an isolated git worktree, reviews the result, and asks a
human to make the final merge decision.
Workflow state lives on the issue itself, so progress stays visible on GitHub and survives process restarts without a
separate queue or workflow database.
[![Ask ChatGPT][ask-chatgpt-badge]][ask-chatgpt]
[![Ask Claude][ask-claude-badge]][ask-claude]
When to use it
- **Use it when:** you work solo or on a small team, have an authenticated codex, claude, or agy CLI, and want
issue-to-PR autonomy without running a separate planner, queue, or workflow database. You decide what to merge.
- **Don't use it when:** you need a hosted service or automatic merges, cannot let agents run with the host account as
their security boundary, or need issue trackers other than GitHub.
How it works
An issue normally follows this path:
The decomposer can split large work into child issues. The implementer commits in a dedicated worktree, the reviewer
requests fixes until the change is ready, and the orchestrator opens or updates the pull request. The reviewer declares
the verification its verdict relies on, which the orchestrator publishes on the pull request before acting on it; an
approval without passing evidence covering every configured VERIFY_COMMANDS command waits for a human. Oversized
changes, conflicts, retries, and human decisions take explicit side paths; pull requests are never merged automatically.
See the [state-machine overview][states] for labels and transitions, and the
[workflow guide][workflow] for agent roles and session behavior.
Requirements
- Linux, Git, and Python 3.12 or newer. CI tests Python 3.12, 3.13, and 3.14; newer versions are not tested.
- pipx 1.16.0 or newer with a Python 3.12 or newer interpreter.
- An authenticated CLI for every configured role. Defaults are
claude for decomposition and implementation, and
codex for review. Any role can instead use
Antigravity (agy).
- A GitHub repository and a fine-grained personal access token with read/write access to Contents, Issues, and Pull
requests, plus read-only access to Metadata.
Agents run with their approval and sandbox checks disabled, so the host account is the security boundary. Read the
[security checklist][security] before using the orchestrator on a public or untrusted repository.
Quick start
Install the published package from PyPI:
Open a new terminal after pipx ensurepath if the command is not yet on PATH. If pipx selects an older Python,
use pipx install --python python3.12 chipping-orchestrator with an installed supported interpreter.
The quick start resolves runtime dependencies from PyPI without poetry.lock, tested constraints, or a 14-day hold;
use the [pinned installation procedure][pinned-installation] for the release's tested dependency versions.
Log in each agent CLI the roles use, then, from the top of a local clone of the repository to manage and in a shell
whose PATH finds those CLIs, set the orchestrator up as a systemd user service, start it, and look at it:
With no configuration yet, init first asks for it at the terminal, one question per setting, each default in
brackets for Enter to take:
- the local clone, the current directory by default, and the repository and branch pull requests target, read off the
clone's GitHub remote;
- the repository's GitHub token, typed at a hidden prompt that offers an exported GITHUB_TOKEN, and checked with one
read-only GitHub call; a token already stored for the repository is kept without asking;