chunk-review

A local-first, chunked PR-review surface — a richer medium between a reviewer and their coding agent than chat, with GitHub-backed sharing that needs no hosted chunk-review service.

The agent breaks a branch's diff into logical chunks (not files), each with a narrative brief, risk rating, review-effort estimate, and "worth scrutinizing" hints. The reviewer walks the chunks in a local web UI, approves or requests changes per chunk, and leaves line-anchored comments. The agent reads that feedback, fixes/answers/rebuts, and replies into the same threads. Chunks whose code changed after a verdict automatically flip to stale for re-review.

Reviews can stay entirely local or be published to an existing GitHub pull request. Shared reviews use each person's authenticated gh session and persist manifests, per-reviewer chunk verdicts, and native review threads in GitHub. There is no chunk-review account, database, GitHub App, or public service.

Install

Run it directly from npm in the repository you want to review:

npx chunk-review serve

Or install the CLI globally:

npm install --global chunk-review
chunk-review serve

To install the bundled agent workflows for Codex on macOS, download the package archive and copy package/skills into the user-level skills directory. This is normally ~/.codex/skills; CODEX_HOME and an explicit AGENT_SKILLS_DIR override are respected:

agent_skills_dir="${AGENT_SKILLS_DIR:-${CODEX_HOME:-$HOME/.codex}/skills}"
chunk_review_package="$(npm pack chunk-review --silent)"

mkdir -p "$agent_skills_dir"
tar -xzf "$chunk_review_package" --strip-components=2 -C "$agent_skills_dir" package/skills

rm "$chunk_review_package"

Claude Code uses ~/.claude/skills for personal skills. The equivalent macOS install is:

agent_skills_dir="$HOME/.claude/skills"
chunk_review_package="$(npm pack chunk-review --silent)"

mkdir -p "$agent_skills_dir"
tar -xzf "$chunk_review_package" --strip-components=2 -C "$agent_skills_dir" package/skills

rm "$chunk_review_package"

For another coding agent, set AGENT_SKILLS_DIR to its user-level skills directory before running the Codex snippet.

Workflow

Shared through GitHub

The author prepares and publishes the review:

# In the PR branch, after generating the manifest with $chunk-review or /chunk-review
chunk-review publish https://github.com/OWNER/REPO/pull/123

Each reviewer needs Node.js 20+, gh, and access to the repository:

gh auth status
npx chunk-review open https://github.com/OWNER/REPO/pull/123

The command starts the UI on an available local port and opens it in the default browser. The UI creates a GitHub pending review for that reviewer. Chunk verdicts update its summary, line and file comments become native pending review threads, and Submit GitHub review publishes everything together as an approval, request for changes, or comment-only review. Multiple reviewers keep independent chunk statuses.

To address submitted feedback from the PR branch:

chunk-review feedback list --pr https://github.com/OWNER/REPO/pull/123 --pending
chunk-review feedback add --pr https://github.com/OWNER/REPO/pull/123 \
  --chunk api-validation --kind resolution --reply-to ghc123456 \
  --body "Handled in src/api.ts:42; invalid input now returns 400."

After code changes, refresh the manifest with the agent workflow and publish again. Publication is immutable and idempotent: an unchanged manifest reuses its existing publication; a changed manifest creates a new revision.

Local only

1. In an agent session on your branch, invoke the bundled chunk-review workflow → generates the manifest.
2. In the repo: chunk-review serve → open the unique local URL it prints and review.
3. Back in the agent, invoke the bundled address-review workflow → works through your open comments, replies in-thread, and refreshes the manifest.
4. Repeat until every chunk is approved (chunk-review status for a one-liner).

How it works

• chunk-review hunks parses git diff <base>...HEAD into hunks with content-hashed ids (line-number-independent, so pure moves keep identity).
• The agent writes manifest.json mapping every hunk to exactly one chunk (chunk-review validate enforces coverage).
• Review state lives in ~/.local/share/chunk-review/<repo>/<branch>/ as manifest.json + append-only feedback.jsonl — human-readable, no database.
• chunk-review publish validates the manifest against both the local diff and GitHub's PR diff, then adds a readable PR comment with a compressed, versioned manifest marker.
• chunk-review open reconstructs the diff through the GitHub API and uses the reviewer's existing gh credentials. Draft feedback lives in a native pending GitHub review and remains private until submission.
• Tool-created GitHub comments carry hidden chunk and hunk ids, so replies and resolution round-trip without guessing from line numbers.
• The server derives chunk status live: a verdict + missing hunk ids ⇒ stale; live hunks not in the manifest ⇒ "unassigned" warning.
• The local HTTP server binds only to 127.0.0.1 and requires a random per-process session token for API calls.
• serve and open ask the operating system for an available port by default, so multiple reviews can run concurrently. Pass --port to pin one explicitly.
• Agent workflows ship in skills/. Any coding agent that can run a CLI and write JSON can implement the same protocol.

CLI

chunk-review serve [--repo .] [--base origin/main] [--port PORT]
chunk-review publish <pr-url> [--repo .] [--base origin/main]
chunk-review open <pr-url> [--port PORT]
chunk-review hunks|paths|validate|status [--repo] [--base]
chunk-review status --pr <pr-url>
chunk-review feedback list [--pending] [--pr <pr-url>]
chunk-review feedback add --chunk <id> --kind comment|verdict|resolution
                          [--body ..] [--reply-to <id>] [--resolves]
                          [--comment-kind question|nitpick|blocking] [--verdict approved|changes_requested]
                          [--pr <pr-url>]
chunk-review feedback resolve <id> [--pr <pr-url>]

Current GitHub constraints

• A reviewer cannot mix a manually started pending GitHub review with a chunk-review pending review. Submit or discard the manual draft first.
• If the PR advances while a review is pending, submit or discard that snapshot before reviewing the new publication. The tool does not silently move comments to new lines.
• GitHub may suppress diff content for exceptionally large pull requests. Publication rejects a manifest when the GitHub diff cannot be reconstructed exactly; use local mode or split the pull request in that case.
• Comments created outside chunk-review are not imported yet. Tool-created native threads round-trip exactly through their embedded marker.

Later

• Map ordinary native GitHub review comments back into chunks by path and diff line.
• Optional GitHub check showing whether the latest publication is behind PR HEAD.
• Syntax highlighting & word-level diff tokens in the diff view.