Roundfix

Roundfix is a local-first Go CLI that resolves pull request review feedback and executes Spec Task Graphs with local coding agents. It fetches unresolved CodeRabbit findings as local markdown artifacts, assigns bounded Batches or Tasks to an ACP Agent runtime, verifies every change with your repository's own gate, creates Daemon-owned commits, and pushes only when nothing unresolved remains.

It is not a workflow engine, CI healer, or task orchestrator. It runs two loops — review resolution on an Open Pull Request, and Spec Task Graph execution — plus the support commands that keep a machine Run-ready (setup, doctor, upgrade, gc, settle, archive, stop).

The spec pipeline it runs is CONTEXT-driven development, adapted from Matt Pocock's skills work — see source and attribution.

Install

Roundfix ships through npm as a roundfix launcher with per-platform binary packages (darwin/linux x64+arm64, windows x64):

npx roundfix --version        # run once without installing
npm install -g roundfix       # or: bun add -g roundfix

Then make the machine Run-ready and check it:

roundfix setup     # verifies Node, pinned acpx, the Agent probe, config
roundfix doctor    # read-only readiness report; mutates nothing

Requirements

• Node.js 22.13+ with npm/npx (the ACP Agent layer runs through acpx 0.12.0; setup installs the pinned version on confirmation).
• A supported ACP Runtime: codex, claude, or opencode.
• GitHub CLI gh authenticated for the target repository (review loops only).
• Building from source additionally needs Go 1.26+ and make.

roundfix doctor diagnoses all of it — including macOS codex hygiene and whether the runtime accepts your configured Agent Model — with one line per check and a next: action on failures.

Quickstart

Resolve a pull request's CodeRabbit feedback until it is merge-ready:

roundfix watch --source coderabbit --pr <number> --agent codex --until-clean

Execute a Spec's Task Graph (specs live under docs/specs/<slug>/), with the QA gate at the end:

roundfix implement --spec <slug> --agent codex --qa

For scripts, CI, or agents, detach the Run and monitor it without owning it:

roundfix implement --spec <slug> --agent codex --detach
roundfix events <run-id> --follow      # JSONL for automation
roundfix attach <run-id>               # read-only Live Run View for humans

Both loops keep one contract: stdout carries only the deterministic report, diagnostics go to stderr, and exit codes are stable (0 clean, 1 unresolved/failed, 2 preflight, 3 clean-unverified watch, 130 Ctrl-C) — which is what lets an agent drive Roundfix reliably.

Documentation

• Operational guide — the two loops end to end: run, monitor, read outcomes, recover failed Tasks.
• Command reference — every command's flags, output shapes, exit codes, and the boundaries it never crosses.
• Configuration — config precedence, agent and model selection, worktrees and bootstrap, retention, local state paths.
• CONTEXT-driven development — the method behind the spec pipeline.
• Project glossary and architecture decisions — the vocabulary and decision log.
• Release runbook.

Build from source

make build        # writes bin/roundfix
make install      # installs into your Go bin directory

The built CLI is identical to the npm-launched binary — same stdout, stderr, and exit codes.

Development

make verify       # fmt-check -> test -> skills-sync-check -> skills-check -> build

Project layout:

cmd/roundfix/                     CLI entry point
internal/agent/                   ACP Agent runtime execution
internal/cli/                     command parsing, output, and exit codes
internal/config/                  YAML config loading and validation
internal/daemon/                  verification, commits, source resolution, push
internal/preflight/               git, PR, worktree, and push safety checks
internal/reviewsource/coderabbit/ CodeRabbit implementation
internal/rounds/                  Round artifacts, issue parsing, batching
internal/store/                   central Run Database
internal/tui/                     Interactive Input and Live Run View
internal/watch/                   watch state machine
skills/                           shipped skill bundle (synced from .agents/skills)
docs/                             product docs and architecture decisions

License

MIT. See LICENSE.