coding-review-agent-loop

Local command-line orchestration for a coding PR review loop.

Run a local Claude/Codex/Gemini PR review loop using your existing CLI subscriptions,
without paying separate model API costs.

The main advantage is cost and account reuse: the tool shells out to your
already-authenticated local CLIs (claude, codex, gemini, and gh) instead
of calling model APIs directly. If your local agent CLIs are backed by existing
AI subscriptions or authenticated developer accounts, the review loop can use
those existing entitlements rather than requiring separate model API
keys and per-token API billing.

Who This Is For

This is for developers who already use Claude Code, OpenAI Codex CLI, Gemini
CLI, and GitHub, and want one local agent to implement or fix a PR while
another local agent reviews it before merge.

It is especially useful when you are already doing this manually by switching
between agent CLIs and copying review feedback back and forth.

Why Not GitHub Actions?

GitHub Actions-based agent loops usually need model API keys, hosted workflow
permissions, and separate API billing. This tool keeps the loop on your local
machine and uses the CLI accounts you have already authenticated.

That makes it easier to experiment with agent-to-agent review loops before
committing to hosted automation. It also keeps local workspace setup,
credentials, and agent approval prompts under your direct control.

Compared To Similar Tools

Several related projects exist. coding-review-agent-loop is deliberately
positioned as a standalone local CLI for GitHub PR lifecycle orchestration:
one agent creates or fixes a PR, one or more reviewers review it, and the loop
continues until approval.

Agent Backends

Currently supported local agent CLIs:

• Claude Code via claude
• OpenAI Codex CLI via codex
• Gemini CLI via gemini

Install / Use

Clone the repo first:

gh repo clone wwind123/coding-review-agent-loop
cd coding-review-agent-loop

Then install the CLI into a local virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
agent-loop --help

This installs the agent-loop command from your checkout. The tool still
requires local gh, claude, codex, and/or gemini authentication depending
on which agents you use.

Develop This Tool

Use this if you are changing coding-review-agent-loop itself:

gh repo clone wwind123/coding-review-agent-loop
cd coding-review-agent-loop
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest

Quick Start

Start from a GitHub issue when you want the agent loop to use the issue title,
body, and comments as the implementation task. Comments are included oldest to
newest, and prompts tell agents that later comments may refine or supersede the
original issue body:

agent-loop issue 123 --repo OWNER/REPO

For larger or ambiguous issues, add --plan-first to run a plan review on the
issue before code is written. The coder may inspect the checkout but must not
edit files, push, or open a PR during planning. Reviewers approve or block with
AGENT_PLAN_STATE markers. By default the loop posts the approved plan summary
and stops; add --implement-after-approval to continue into the normal PR flow:

agent-loop issue 123 --repo OWNER/REPO --plan-first --implement-after-approval

Provide a one-off task directly when there is no issue yet:

agent-loop task "Add a health check endpoint" --repo OWNER/REPO

Run the loop against an existing pull request when you want another review and
iteration pass:

agent-loop pr 456 --repo OWNER/REPO

If --repo is omitted, the tool runs gh repo view from the current working
directory, or from --codex-dir when that flag is provided, and uses the
detected OWNER/REPO. Pass --repo explicitly when running outside the target
repository.

When --claude-dir, --codex-dir, or --gemini-dir is omitted for an active
agent, the tool creates or reuses a repo-scoped temporary checkout such as
/tmp/coding-review-agent-loop/OWNER-REPO/codex/repo. Existing clean temp
checkouts are fetched and fast-forwarded on the base branch before the agent
runs. Default temp checkouts are tool-owned and disposable; if one is dirty,
the tool resets and cleans it before reuse. Explicit persistent directories are
kept conservative: dirty explicit workdirs fail clearly, and existing git
checkouts must point at the requested repository. Use explicit persistent
directories for large repositories, long-lived agent worktrees, or setups that
should survive /tmp cleanup or reboot.

Agent memory is enabled by default. Before invoking agents, the loop creates or
refreshes advisory repo memory in a durable, repo-scoped user cache directory
such as ~/.cache/coding-review-agent-loop/repos/OWNER-REPO/memory on Linux:
repo summary, architecture map, module index, execution/test profile, toolchain
facts, and changed files since the previous memory commit. On macOS the default
root is ~/Library/Caches/coding-review-agent-loop; on Windows it is
%LOCALAPPDATA%/coding-review-agent-loop/Cache. Agent prompts state that this
cache is stale-prone orientation only, and that agents must inspect source files
and PR diffs directly for correctness claims. The cache is local-only. Disable
it with --no-agent-memory, force a refresh with --refresh-agent-memory,
customize the location with --agent-memory-dir PATH, or refresh only test
command facts with --refresh-test-profile. Relative --agent-memory-dir
values are resolved inside the coder checkout. If you keep sensitive repo
details out of local cache retention, use --no-agent-memory or a custom
short-lived location. If the previous memory commit is unavailable or no longer
diffable, the loop logs the git failure and treats all tracked files as changed
for that refresh.

By default Claude is the coder and Codex is the reviewer. Reverse that with:

agent-loop task "Fix the flaky test" --repo OWNER/REPO --coder codex --reviewer claude

Use Gemini as either side of the loop:

agent-loop task "Improve error handling" \
  --repo OWNER/REPO \
  --coder gemini \
  --reviewer codex

agent-loop pr 456 \
  --repo OWNER/REPO \
  --reviewer gemini

Repeat --reviewer to require approvals from multiple reviewers. The PR is
approved only after every configured reviewer approves in the same round. The
coder may also be listed as a reviewer when you want the same agent to work in
separate coding and review passes:

agent-loop pr 456 --repo OWNER/REPO --reviewer codex --reviewer claude

When --approved-followups is set to summarize, issue, or a fix-and-*
mode, approved reviews may include future work under:

### Future follow-ups
- Add a follow-up test.

Reviewers should use that section only for substantial work that is better
handled in a separate issue or PR. The legacy heading
### Non-blocking follow-ups is still parsed as future work for compatibility.

When --approved-followups uses a fix-and-* mode, approved reviews may also
include small, localized, low-risk current-PR cleanup under:

### Same-PR follow-ups
- Rename a helper before merge.

Same-PR follow-ups are sent back to the coder in the existing PR and require a
new review round. They should stay narrowly scoped to files already touched by
the PR or directly adjacent code; larger redesigns and independent work belong
under Future follow-ups. After same-PR follow-ups trigger another round, only
future follow-ups restated in the final approval round are summarized or turned
into issues. The issue modes create at most three follow-up issues to avoid
issue noise.

By default, --approved-followups=ignore asks reviewers not to include
approved-review follow-up sections. Reviewers should mark the review blocking
instead when cleanup should be fixed before merge.

--approved-followups accepts:

• ignore: ignore approved follow-up sections. This is the default.
• summarize: post future follow-ups as a grouped PR comment.
• issue: create GitHub issues for future follow-ups, then comment with the created issue links.
• fix-and-summarize: send same-PR follow-ups to the coder for another review round, then summarize future follow-ups after final approval.
• fix-and-issue: send same-PR follow-ups to the coder for another review round, then create issues for future follow-ups after final approval and comment with the created issue links.

To keep a grouped record on the PR or create follow-up issues, use:

agent-loop pr 456 --repo OWNER/REPO --approved-followups summarize
agent-loop pr 456 --repo OWNER/REPO --approved-followups issue
agent-loop pr 456 --repo OWNER/REPO --approved-followups fix-and-summarize

Only bullets inside the Same-PR follow-ups, Future follow-ups, and legacy
Non-blocking follow-ups sections are parsed. Each section ends at the next
heading, HTML marker, or agent signature, so final protocol markers are not
mistaken for follow-up text.

For trusted local automation that must run without approval prompts:

agent-loop issue 123 --repo OWNER/REPO --dangerous-agent-permissions

Real Example

This project uses agent-loop to improve itself. This command asked Codex to
review existing issue and PR feedback, with both Claude and Gemini reviewing
the result. The work became PR #13:
https://github.com/wwind123/coding-review-agent-loop/pull/13

~/tools/coding-review-agent-loop/.venv/bin/agent-loop task \
  "Please go over all the issue and pr reviews again and see if there's any non-blocking issues still worth addressing but have not been addressed." \
  --repo wwind123/coding-review-agent-loop \
  --coder codex \
  --reviewer claude \
  --reviewer gemini \
  --dangerous-agent-permissions

See docs/local_agent_loop.md for the architecture diagram, full usage, and safety notes.

Test

python -m pytest

Tests use fake subprocess runners. They do not call real claude, codex, gemini, or gh.