romp — label an issue, get a pull request

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Requirements

git 2.35+ — the first release with reliable worktree support
gh — authenticated via gh auth login
codex or claude, logged in
Go 1.25+ to build, or a release binary

Install

Go install (recommended)

go install github.com/BRO3886/romp/cmd/romp@latest

Download a release

Apple Silicon:

curl -LO https://github.com/BRO3886/romp/releases/latest/download/romp-darwin-arm64.tar.gz
tar xzf romp-darwin-arm64.tar.gz
mkdir -p ~/.local/bin && mv romp ~/.local/bin/romp

Intel:

curl -LO https://github.com/BRO3886/romp/releases/latest/download/romp-darwin-amd64.tar.gz
tar xzf romp-darwin-amd64.tar.gz
mkdir -p ~/.local/bin && mv romp ~/.local/bin/romp

Build from source

git clone https://github.com/BRO3886/romp.git
cd romp
make build
# Binary at ./bin/romp

Quickstart

romp reads the repo from your current directory’s origin remote.

Commands

Mon, 01 Jan 0001 00:00:00 +0000

romp is a single binary. Every command runs against the repo in your current directory (resolved from its origin remote) unless noted.

Command	What it does
`romp init`	Write `romp.toml`, create the labels, update `.gitignore`.
`romp watch`	Poll and work labelled issues. One repo, foreground.
`romp run -i N`	Run one issue now, ignoring the label.
`romp status`	In-flight jobs. `--all` for every repo.
`romp history`	Recently finished jobs. `--all` for every repo.
`romp logs <codename\|issue> [-f]`	Show or follow a job’s log.
`romp cancel <issue>`	Kill a running job and abandon it.
`romp gc`	Remove stale worktrees and old history. Dry-run unless `--apply`.
`romp doctor`	Check git, gh auth, harness, config.

`romp run`

Run one issue now, in the foreground, without claiming it in the job table.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration is TOML. romp init writes a starting romp.toml:

label          = "romp"           # trigger label
claimed_label  = "romp:claimed"
blocked_label  = "romp:blocked"
base           = "main"           # default: repo default branch
width          = 3
timeout        = "25m"

[verify]
build = "go build ./..."
test  = "go test ./... -count=1"
lint  = "golangci-lint run"      # optional

[scope]
protected = ["testdata/**", "internal/testutil/**", ".github/**"]
ignore    = ["vendor/**", "node_modules/**"]

[harness]
default   = "codex"              # claude | codex
model     = ""
effort    = "high"               # claude: low..max; codex: + none, minimal, ultra
max_turns = 30                   # claude only

[prompt]
template = ".romp/prompt.md"     # optional
brief    = ".romp/DESIGN.md"     # optional

Precedence

Config merges in a fixed order — later layers override only the fields they set:

Goal Contract

Mon, 01 Jan 0001 00:00:00 +0000

romp hands the agent a finish line, not a task description. The rendered prompt is the single contract between romp and the agent, and it is harness-agnostic: claude and codex receive the same structure.

The four sections

GATE — reject the issue before touching code if it’s ambiguous, contradictory, or under-scoped. Don’t invent missing criteria.
DONE — every acceptance criterion met, on a clean tree.
PROVE IT — run the verify command and show the fresh passing output.
CONSTRAINTS — no deleted, skipped, or weakened tests, no hardcoded expected values, no out-of-scope files, no git commit/git push.

The GATE is the point. An issue is shippable only if all three of these are already written in the issue body:

Outcomes

Mon, 01 Jan 0001 00:00:00 +0000

Every job ends in exactly one named outcome. There is no silent grey area.

Outcome	What you get
done	PR opened, trigger label removed.
blocked	No PR. `romp:blocked` label + gap comment.
no-changes	Agent exited clean with no commits. No PR.
red	Verify failed on independent re-run. No PR, worktree kept.
timeout	Exceeded `timeout`. Killed, worktree kept.
cancelled	You cancelled. Worktree, branch, and both labels removed.
error	git/gh failure (incl. rate limits outliving retries). Re-claimed later.

rate-limited is not an outcome: it names the in-job GitHub retry, not a terminal state.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

romp is a Go CLI that drives your local coding agent. It is deliberately minimal: the durable source of truth is GitHub, and romp adds only the machinery to claim, isolate, and verify work.

Job lifecycle

Poll — watch lists open issues carrying the trigger label every 60 seconds. The label is the entire queue; there is no local backlog.
Claim — atomic insert (unique on repo + issue), claim label, assign @me. Concurrent watchers on other machines skip claimed issues.
Worktree — each job runs in a fresh git worktree branched from the default branch. Never the local tree; the base is deterministic.
Agent — the goal contract is rendered and handed to the harness (claude or codex).
Verify — romp re-runs every [verify] command itself. The agent’s own “tests pass” is never trusted.
PR or block — green and scoped means a PR and label removal; an under-scoped issue becomes blocked with a gap comment.

Components

romp/
├── cmd/romp/          # Cobra commands (init, watch, run, status, ...)
├── internal/
│   ├── config/        # TOML layering, language detection, effort validation
│   ├── harness/       # claude + codex adapters behind a Run/Name interface
│   ├── prompt/        # goal-contract template rendering
│   ├── runner/        # job pipeline: worktree → agent → verify → PR/block
│   ├── watch/         # poll loop + claim + cancel socket
│   ├── job/           # SQLite job table + outcome history
│   ├── gh/            # GitHub client with rate-limit retry
│   ├── git/           # worktree and branch management
│   └── codename/      # deterministic adjective_name per job
└── docs/adr/          # design decisions

Isolation and concurrency

Worktree isolation — concurrent jobs never share a checkout.
Width — an in-memory semaphore bounds concurrent jobs per repo.
Cross-machine dedupe — the claim label, not any local state, is the authority across machines.
Crash recovery — a fresh watcher clears only its own stale in-flight rows and reconciles issues whose romp-N branch already has an open PR.

Observability

Every job gets a codename — an adjective_name pair like sunny_naruto, derived deterministically from the repo and issue number. The codename prefixes every log line, names the per-job log file, and is the primary column in status.

Safety

Mon, 01 Jan 0001 00:00:00 +0000

romp runs a coding agent on your machine. That agent can run arbitrary tools and edit files. Read this before you let it loose.

The label is privileged

The agent is driven by text that anyone with repo write access can author — the issue title and body. Adding the trigger label to an issue is authorizing your machine to execute whatever that issue says. Treat the trigger label as a privileged action and label only issues you would run yourself.