Agent Review

Local, verifiable review trails for AI coding agents.

When an AI agent builds a feature for you, the diff shows what changed but not why, which tests actually ran, or what risks the agent knew about. Agent Review records that evidence while the agent works and turns it into a review package you (and your reviewers) can trust:

• a review session bound to a task and a git branch;

• an append-only event journal of edits and commands;

• restorable checkpoints (file snapshots, never git reset);

• structured intents per logical change: what, why, expected behavior, risk, alternatives, limitations;

• test evidence: exact command, exit code, duration, capped and redacted output;

• a machine-readable Change Package (change-package.json, schema agent-review/v1) and a human-readable review.md;

• optional: a GitHub Draft PR with a summary and a few inline comments placed on the exact diff lines they explain.

It runs on plain Git with no backend, no GitHub App and no extra VCS. Everything stays on your machine until you explicitly confirm a publish.

Works with OpenCode (native plugin) and Claude Code (and any other MCP host) via an MCP stdio server.

Example output

An excerpt of a generated review.md (from npm run demo):

## Logical Changes

### 1. refresh token rotation
- What changed: added in `src/token.ts`
- Why: refresh tokens were static; rotation limits replay windows
- Expected behavior: every refresh rotates the token
- Risk: medium

## Test Evidence

### Run 1
- Command: `npm test`
- Result: **passed** (exit code: 0)
- Duration: 412 ms

## Risks
- Branch was created from protected branch "main".

Related MCP server: ITHZ MCP

Safety model

Agent Review is built to be safe to hand to an autonomous agent:

• No destructive git. It never runs reset --hard, clean, force-push, history rewrites or branch deletion. Rollback restores snapshotted files only, after taking a safety checkpoint, and never deletes files.

• Confirmation gates. Creating a branch from a protected branch (main/master/develop), restoring a checkpoint, and every GitHub publish require an explicit confirm/confirmed: true passed after the user agrees. Without it the tools only return a preview.

• Evidence, not reasoning. Only observed facts, explicit decisions, command results and statically computed risks are recorded. No chain-of-thought.

• Redaction. Tokens, keys and credentials are redacted before anything is written to the journal or the package; test output is size-capped.

• No code leaves the machine for comment generation; GitHub publishing goes through your own authenticated gh CLI only.

• Restricted test runner. run_tests takes a single command with no shell metacharacters and rejects destructive programs.

Install

Requirements: Git, Node ≥ 22.6, and for GitHub publishing the GitHub CLI (gh auth login).

git clone https://github.com/frxnxtic/agent-review.git
cd agent-review
npm install

Claude Code (or any MCP host)

1. Register the MCP server in your project's .mcp.json:

   {
     "mcpServers": {
       "agent-review": {
         "command": "node",
         "args": ["/abs/path/to/agent-review/bin/agent-review-mcp.js"]
       }
     }
   }

2. Add the journaling hook to .claude/settings.json. It records edits and shell commands, but only while a review session is active:

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
           "hooks": [
             { "type": "command", "command": "node /abs/path/to/agent-review/bin/agent-review-claude-hook.js", "timeout": 10 }
           ]
         }
       ]
     }
   }

3. Add the skill that teaches the agent the workflow:

   mkdir -p .claude/skills
   ln -s /abs/path/to/agent-review/skills/agent-review .claude/skills/agent-review

4. Restart Claude Code. The tools appear as mcp__agent-review__agent_review_*.

The project root is resolved from AGENT_REVIEW_PROJECT_ROOT, then CLAUDE_PROJECT_DIR, then the server's working directory.

OpenCode

Symlink the plugin and the skill into your project (file symlinks in .opencode/plugins/ load like regular plugin files), then restart OpenCode:

ln -s /abs/path/to/agent-review/src/plugin.ts .opencode/plugins/agent-review.ts
ln -s /abs/path/to/agent-review/skills/agent-review .opencode/skills/agent-review

The plugin journals file edits and tool calls through OpenCode's own hooks.

Tools

Typical workflow

1. Start: agent_review_start { task }. On a protected branch the tool proposes a branch name; after the user approves, call again with confirm: true. A dirty working tree is recorded as a risk, never reset.

2. Work. Take checkpoints before risky edits, and call agent_review_record_intent once per logical change.

3. Test: agent_review_run_tests { command: "npm test", reason }.

4. Build: agent_review_build_package, then read .agent-review/review.md.

5. Optional PR: agent_review_prepare_pr, show the preview to the user, then agent_review_publish_pr { confirmed: true, allowPush: true }.

Tip: if your working tree contains unrelated changes, commit your feature yourself and publish with allowCommit: false. The tool's own commit step stages everything (git add -A).

GitHub Draft PR reviews

Enable publishing in .agent-review/config.json ("github": { "enabled": true }). With it disabled, status and prepare-pr still work and publishing fails.

• Draft PRs only by default. It never merges, never changes the base branch, never assigns reviewers or labels, and reuses an existing open PR instead of creating a duplicate.

• Inline comments attach only to added lines of the current PR diff, at most one per logical change, capped by maxInlineComments (default 8). They skip generated files, lockfiles and formatting-only changes. A change with no mappable line becomes a note in the PR body; the mapper never guesses.

• Updates are surgical. Each comment carries a hidden marker (agent-review:session=…;change=…); after a new push, only Agent Review's own comments are replaced. Human and other-bot comments are never touched.

• The summary and comments are review context, not guarantees of correctness.

Manual end-to-end test guide: docs/manual-github-test.md.

CLI

The GitHub workflow is also available from the shell (run from your project directory):

node /abs/path/to/agent-review/bin/agent-review.js github status [--base main]
node /abs/path/to/agent-review/bin/agent-review.js github prepare-pr [--base main] [--max 8]
node /abs/path/to/agent-review/bin/agent-review.js github publish-pr [--allow-commit] [--allow-push] [--no-draft] --confirm
node /abs/path/to/agent-review/bin/agent-review.js github update-review [--pr <n>] --confirm

Nothing is published without --confirm.

Where data lives

.agent-review/
├── config.json          # committable configuration
├── change-package.json  # committable review artifact
├── review.md            # committable review summary
├── github/              # committable PR preview artifacts
├── events.jsonl         # gitignored journal (append-only)
├── session.json         # gitignored current/last session
├── checkpoints/         # gitignored checkpoint metadata
└── snapshots/           # gitignored file snapshots

Add the runtime files to your project's .gitignore:

/.agent-review/events.jsonl
/.agent-review/session.json
/.agent-review/checkpoints/
/.agent-review/snapshots/

Configuration

.agent-review/config.json is created on first use:

Limitations

• Snapshots cover only files that were changed at checkpoint time.

• Symbol extraction is regex-based, not AST-based.

• The Change Package reflects the working tree, so uncommitted unrelated changes are counted; the dirty state at session start is recorded as a risk.

• Automatic journaling depends on host hooks (OpenCode plugin hooks, Claude Code PostToolUse); other MCP hosts get the tools without automatic journaling.

Development

npm run typecheck         # tsc --noEmit
npm test                  # unit + mock-integration tests (node --test)
npm run test:integration  # full local arc + mock-GitHub publish arc
npm run demo              # runs a demo arc and prints review.md

Domain logic lives in src/*.ts. The host adapters are src/plugin.ts (OpenCode), src/mcp.ts (MCP server) and src/claude-hook.ts (Claude Code hook), all built on the shared handlers in src/handlers.ts.

License

AGPL-3.0