chipping-orchestrator

Autonomous GitHub issue → reviewed PR pipeline for Claude Code, Codex CLI, and Antigravity CLI.

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.

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:

workflow:decomposing → workflow:ready → workflow:implementing
  → workflow:validating → workflow:documenting → in_review
  → done or rejected

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. A final docs pass that commits documentation changes sends the pull request back to workflow:validating, where the developer reports on the new head and a fresh reviewer verifies it before another docs pass. One that changes nothing hands the pull request on only while the approval's verification evidence still proves current behind it; evidence that no longer does is invalidated, and the pull request goes back for a fresh review. Oversized changes, conflicts, retries, and human decisions take explicit side paths; pull requests are never merged automatically.

See the state-machine overview for labels and transitions, and the workflow guide 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 before using the orchestrator on a public or untrusted repository.

Quick start

Install the published package from PyPI:

pipx install chipping-orchestrator
pipx ensurepath

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 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:

chipping-orchestrator init
chipping-orchestrator start
chipping-orchestrator status

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;
• the GitHub logins whose issues and comments the orchestrator acts on, the token owner's by default, and those to mention when a human is needed, the same by default;
• the agent each role runs, shown with whether it is on PATH, and any further repository.

A refused answer is asked again with the reason. Nothing is written until the last question confirms the files it names, so Ctrl+C leaves the host as it was. Then init saves each token to ~/.config/<owner>/<name>/token, writes ~/.config/chipping-orchestrator/.env, checks the setup the way the service will read it, GitHub calls included, and installs and enables ~/.config/systemd/user/chipping-orchestrator.service for this installation's interpreter and the shell's PATH, with linger where logind allows it, without starting the service. The orchestrator's own repository does not need to be cloned.

start checks the settings locally once more, without asking GitHub, then starts the service and confirms it stays active, printing its last journal lines if it does not. status prints the installed version, the .env and the unit, then systemctl --user status: run it after a start, a reboot, or an edit to see whether the poller is running, and follow its output with journalctl --user-unit chipping-orchestrator.service -f. stop, restart, and remove manage it from there, remove deleting the unit and keeping the setup. Run init again when the agents move to other directories: with .env in place it asks nothing and rewrites only the unit. The user service guide covers the unit, linger, each command, and replacing a hand-written orchestrator.service.

The same setup runs without prompts, as a script or a host without a terminal needs: there, init refuses a missing .env and names these commands.

chipping-orchestrator set-token acme/api < "$HOME/acme-api-token.txt"
chipping-orchestrator configure --clone /home/alice/src/acme-api --authors alice
chipping-orchestrator init

set-token reads the token from standard input, at a hidden prompt on a terminal, checks it reaches the repository, and writes its token file owner-only; configure writes .env for the repository a local clone names, trusting the GitHub logins given as authors, and the package setup instructions cover its other options. Tokens in .env are deliberately ignored, and the token is never a command-line argument.

Either way, .env sets these; edit it to change any of them, then chipping-orchestrator restart:

• REPOS — the repository to manage, written owner/name|target_root|base_branch: its GitHub owner/name, the absolute path to an existing local clone of it, and the branch its pull requests target. For example:

  REPOS=acme/api|/home/alice/src/acme-api|main
  

  The template explains the two optional trailing fields; several repositories are more entries in the same setting, which onboarding's further repositories and add-repo add.

• HITL_HANDLE — GitHub users to notify when human input is needed: the people to mention, else the authors.

• ALLOWED_ISSUE_AUTHORS — required: the GitHub logins whose issues and comments the orchestrator acts on; it refuses to start while this names nobody.

• DEV_AGENT, REVIEW_AGENT, and DECOMPOSE_AGENT — the agent each role runs: claude, codex, and claude unless onboarding or --dev-agent, --review-agent, or --decompose-agent says otherwise.

• LOG_DIR — an absolute directory outside the pipx environment, so logs survive package upgrades.

Nothing from .env.example.advanced is needed: it holds optional operational settings and, in a section of their own, the developer settings for working on the orchestrator itself.

To run the poller in the foreground instead of as a service, check the setup and run it:

chipping-orchestrator check
chipping-orchestrator run

A foreground run also accepts one GITHUB_TOKEN exported in its launch environment in place of the token files, for every repository. check ignores that export, since a service is not started from that shell, and reports each repository without a token file as a problem, so store the tokens with set-token for any setup a service will run.

On first start, the orchestrator creates its labels and begins polling open issues. Each issue gets its own worktree under wt-orchestrator, beside the first repository's clone. File a small issue to exercise the workflow; a completed change stops at in_review for a human to merge.

The configuration reference covers credentials, agent routing, every setting, and advanced examples. The operations guide covers run modes, upgrades and rollback, running more than one poller on one host, and systemd deployment. For unconstrained, unpinned installs, use pipx upgrade chipping-orchestrator after stopping the poller and reviewing release notes. Constrained installs upgrade by repeating the pinned procedure in the operations guide with the new release's constraints. Package upgrades are operator-initiated. Upgrading to v0.14.0 from v0.13.0 or earlier moves the poller to chipping-orchestrator run: the bare command prints help and exits. Read the v0.14.0 release and upgrade notes and the package upgrade procedure before upgrading a host whose scripts or systemd unit run it. A release or source revision that cannot read the work the running poller owns is deployed without migration: stop and hold every poller, keep what the new build cannot read away from it and in place for a human to decide on, then install, check, and start it deliberately. Nothing converts earlier workflow state, and breaking changes reach main as they merge, not first at a release tag.

Asking the orchestrator a question

Apply the question label to an open issue for a read-only answer. The configured DECOMPOSE_AGENT replies on the issue, keeps the same session for follow-up questions, and stops when the issue is closed.

See the question-stage contract and handler behavior.

Discussing an issue's architecture

Apply the discussion label to work through design choices before implementation. The decomposer presents options, continues the conversation from your replies, and writes only plans/issue-<number>.md after you confirm the design. The orchestrator then opens a plan pull request for a human to merge, reject, or route into implementation.

See the discussion-stage contract and handler behavior.

Holding and unsticking an issue

Use the control named by the orchestrator's park comment:

Control	Purpose
backlog	Prevent pickup until the label is removed.
paused	Freeze an in-flight issue without discarding its state; remove the label to resume.
/orchestrator continue	Retry a recoverable stalled run or renew a spent daily retry budget when requested.
/orchestrator authorize-oversized <commit>	Allow the exact oversized commit named by the park to publish.
/orchestrator add-review-rounds N	Grant more reviewer rounds after the configured cap is reached.
/orchestrator add-agent-runs N	Raise the lifetime agent-run allowance for that issue.

Commands are accepted only in the contexts and formats described by the park comment; ordinary guidance and control commands are intentionally not interchangeable. See the control-label reference and delivery-stage behavior for trust checks, limits, recovery, and exact effects.

Observability

orchestrator.log records process and issue activity, while analytics.jsonl records transitions, timing, agent outcomes, usage, and cost estimates. Both live under LOG_DIR, set to ~/.local/state/chipping-orchestrator/logs by package setup. An explicit ANALYTICS_LOG_PATH can place analytics elsewhere. Optional surfaces add an audit log, a Postgres-backed analytics dashboard, and a file-backed trajectory viewer without becoming part of workflow state. The dashboards are source-checkout developer tools; their dependencies and launch commands are in the developer guide.

See the observability overview for every surface.

Managing multiple repositories

One process manages several repositories. To add one to an installed setup, store its token, add its entry, and restart the service so it reads the new entry:

chipping-orchestrator set-token acme/web
chipping-orchestrator add-repo --clone /home/alice/src/acme-web
chipping-orchestrator restart

add-repo reads the repository, the remote that points at it, and the branch pull requests target off the clone, the way configure does, and adds the entry to the end of the REPOS line in ~/.config/chipping-orchestrator/.env, keeping every other line as it was. --repo, --base-branch, and --remote replace what it reads, and --parallel N lets N of the repository's issues run at once. It refuses a missing .env and a repository REPOS already lists, and says to restart when the service is running, since a service reads REPOS only as it starts. restart checks the setup locally first, a token for the new entry included, and leaves the service running as it was if that check finds a problem. Adding a repository covers every option and refusal.

REPOS itself carries one entry per repository, separated by ; since .env holds each value on a single line, and can still be edited by hand. Edit the first REPOS line rather than adding another: .env keeps the first value it reads for a setting.

REPOS=acme/api|/home/alice/src/acme-api|main;acme/web|/home/alice/src/acme-web|master|upstream|2

Every entry names its own local clone and reads its own token file, ~/.config/<owner>/<name>/token, which chipping-orchestrator set-token <owner>/<name> writes, unless one exported GITHUB_TOKEN covers them all for a foreground run. The optional fourth and fifth fields set the git remote that points at the repository (origin by default) and how many of its issues run at once; they are positional, so setting the limit means writing the remote too. Worktrees and branches are namespaced by repository, and per-repository plus global concurrency limits keep issues from colliding or overwhelming the host.

See the REPOS syntax and parallel-processing settings.

Reference documentation

Browse the documentation website or the documentation index for the complete reference set:

Topic	Covers
Architecture	Process model, agent model, push model, and module ownership
State machine	Labels, state, stage handlers, and lifecycle
Agents	Agent roles, conversation contracts, and command specs
Configuration	Environment variables, defaults, and operator runbooks
Observability	Logs, analytics, dashboards, trajectories, usage, and cost
Security	Deployment checklist and operator-owned controls
Release timeline	Published milestones, release notes, and upgrade guidance

Report suspected vulnerabilities through the private process in SECURITY.md, never through a public issue.

Contributing

See CONTRIBUTING.md for writing issues, setting up a development checkout, running checks, and submitting pull requests. Source-checkout installation, direct Python launches, and the development wrapper are documented in the developer guide.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.