code-eye

Evidence-backed, local-first AI code review for CLI coding agents — pi, Claude Code, and Codex.

Run a quick or deep review, inspect evidence-backed findings on the exact diff lines, and send questions or fixes back to the coding agent. The shared review surface is a purely local browser page; pi can also render an explicit two-pane TUI overlay. /code-eye-web (pi) and the bundled review skills (Claude Code / Codex) open the same local review UI:

Features

• Per-commit review — left pane lists your uncommitted changes plus every commit in base..HEAD (base defaults to main, falls back to master or the origin default branch); the right pane shows the selected commit's diff with GitHub-style red/green coloring and line numbers.
• Evidence-backed findings (ADR-0006) — every structured finding carries a concrete claim, impact, evidence, severity, category, confidence, and exact diff location. The reviewer must try to disprove candidate issues before submitting them.
• Quick / deep modes — quick focuses on changed lines and high-signal risks; deep explores callers, tests, configuration, and invariants outside the diff. Both report checks and explicit reviewed/skipped-file coverage.
• Persistent review rounds — user comments and the latest finding ledger persist in <gitdir>/code-eye/state.json. Deep re-review marks missing findings fixed; quick review preserves findings outside its coverage; dismissed findings stay dismissed. Comments that lose their inline home because code or a parent finding moved remain actionable in an Unresolved conversations section with their original context.
• Human-owned conversations (ADR-0007) — comments keep a stable identity across rounds. After handling one, the agent appends a response with changed locations, Before/After evidence, and checks; the comment becomes agent addressed, but only you can resolve it.
• Selective handoff — queue Fix, Explain, Add test, or Show alternative on any open browser conversation. The selected intent is included with the next agent handoff and clears when the agent responds.
• Agent walkthrough compatibility — legacy walkthrough notes (◆) still render beside your comments (●), but structured reports are the preferred protocol.
• Ask back inline — on the web surface you can reply to an agent note with a question, or adopt its suggestion; both go back to the agent with your other comments. Stale notes (code moved since the walkthrough) are greyed out.
• Browser surface — /code-eye-web [quick|deep] runs the reviewer, then opens findings in your browser via a throwaway 127.0.0.1 server. It shuts down when you submit or close.
• Two-way trigger — start a browser review with /code-eye-web, or let the agent call its review tool after making changes ("walk me through what you changed").
• Quiet closes — only conversations waiting for agent work reach the agent. Agent-addressed conversations stay visible for your approval without re-triggering work; resolved comments and agent findings are never fed back.

Installation

pi

pi install npm:@toddzheng024/code-eye

Or from the git repo:

pi install git:github.com/qiz029/code-eye

Or add it to ~/.pi/agent/settings.json:

{
	"packages": ["npm:@toddzheng024/code-eye"]
}

To try it without installing:

pi -e git:github.com/qiz029/code-eye

Reload a running pi session with /reload.

Claude Code

This repo is a plugin marketplace:

/plugin marketplace add qiz029/code-eye
/plugin install code-eye@code-eye

The plugin bundles an MCP server (code-eye-mcp, run via npx) and two skills: deep review/walkthrough and quick review. Reviews can stay open as long as you like — the server sends progress heartbeats — but if you want to be safe against idle timeouts, set CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0; and if you don't want long review calls auto-backgrounded after 2 minutes, set CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0.

Codex

This repo is a plugin marketplace:

codex plugin marketplace add qiz029/code-eye

then install via /plugins. The plugin bundles an MCP server and a code-eye skill ($code-eye, or just ask to "walk me through the changes"). One required config tweak in ~/.codex/config.toml — the default 60s MCP tool timeout would kill an open review:

[mcp_servers.code-eye]
tool_timeout_sec = 3600
default_tools_approval_mode = "auto"

On both hosts the review runs in your browser (their TUIs have no custom component API — see docs/adr/0004-cross-host-mcp-server.md).

Usage

| Command | Description | |---|---| | /code-eye-web [quick\|deep] | Run an AI review and open it in the browser |

When an agent explicitly opens pi's TUI panel through the review tool (surface: "tui"):

| Key | Action | |---|---| | ↑/↓ | Select commit (left pane) / scroll diff (right pane) | | Tab / Enter / ← | Switch between panes | | PgUp/PgDn | Page through the diff | | n / p | Next / previous finding or legacy agent note | | x | Dismiss the current structured finding | | c / Enter | Add or edit a comment on the current diff line (add/del/context only) | | d | Delete your comment on the current line (agent notes are read-only) | | r | Mark your comment on the current line resolved / reopen it (resolved comments persist but aren't sent to the agent) | | [ / ] | Jump to previous / next comment | | w | Ask the agent for a walkthrough (when none is active) | | Esc | Close the panel (and submit any comments) |

Line comments. Move to a changed line, press c (or Enter on a commentable line), type your note, and press Enter to save. Lines with your comments are marked ●; structured findings and legacy agent notes are marked ◆. Comments and structured finding lifecycle persist across sessions.

When you close the panel:

• If no conversations are waiting for agent work, nothing is sent anywhere — a silent "LGTM". Agent-addressed conversations can remain visible for your approval.
• If the agent opened it via the review tool, your comments come back in the tool result for the agent to address.
• If you started with /code-eye-web, your comments return through the review tool for the agent to address.

The agent can open the panel via the review tool. The preferred input is a structured report; legacy summary/walkthrough stops remain compatible. When returning after handling feedback, it supplies addressedComments with the stable comment id, a summary, changed locations (including Before/After where useful), and checks. The tool blocks until you close the panel, so the conversation picks up right after your review.

Web surface

/code-eye-web [quick|deep] runs the reviewer, then serves findings from an ephemeral 127.0.0.1 server and opens your browser; the server shuts down when you submit or close the tab.

• Click items in the sidebar to switch between uncommitted changes and commits; #i=N in the URL deep-links to an item.
• Hover a diff line and click the blue + to write a multi-line comment (Cmd/Ctrl+Enter saves, Esc cancels); your comments show up as editable "you" cards with a resolve toggle.
• On an open comment, choose Fix, Explain, Add test, or Show alternative to tell the agent what kind of response you want. Agent responses remain visible as a chronological ledger with changed locations, Before/After code, and verification results.
• Findings render as read-only 🤖 cards with severity/category, claim, impact, evidence, confidence, and optional suggestion. Filter by severity, ask a question, dismiss a false positive, or ask the coding agent to adopt a suggestion.
• Comments whose original diff anchor or parent finding disappeared move to Unresolved conversations with their original file, line, and code. Resolve or reopen them there instead of losing the conversation.
• Hidden context between hunks expands in place via ↑ Expand up / ↓ Expand down.

Development

git clone https://github.com/qiz029/code-eye.git
cd code-eye
npm install
npx tsc --noEmit   # type check
npm run build      # bundle the MCP server to dist/code-eye-mcp.mjs

Run it from the working copy:

pi -e ./index.ts

Or symlink it for auto-discovery and hot reload:

ln -s "$PWD" ~/.pi/agent/extensions/code-eye
# then /reload inside pi

How it works

• git.ts — detects the base branch, lists base..HEAD commits plus uncommitted changes (or the "Δ since last review" delta item), and loads per-commit patches via git show / git diff.
• parse-unidiff.ts — parses unified diffs into structured lines (file, old/new line numbers) so walkthrough stops can anchor to exact lines.
• comments.ts — the shared surface model: user comments and read-only agent findings/legacy notes share one anchor format, with conversation status, replies, suggestions, evidence fields, and anchor-staleness checks.
• conversations.ts — selective handoff actions plus the append-only agent response ledger and Before/After evidence.
• review-report.ts — validates structured reviewer output, computes stable finding fingerprints, reconciles quick/deep review rounds, and projects active findings into the shared surfaces (ADR-0006).
• review-state.ts — versioned on-disk ledger in <gitdir>/code-eye/state.json: persisted user conversations, agent responses, latest structured report, and the last-reviewed HEAD. Older state migrates on read.
• walkthrough.ts — converts agent walkthrough stops into agent comments (ADR-0001).
• review-view.ts — the two-pane TUI overlay component, built on pi's ctx.ui.custom() overlay API.
• web-review.ts — the browser surface: an ephemeral 127.0.0.1 server serving a GitHub-style review page (ADR-0003).
• mcp-server.ts — the cross-host entry point: an MCP stdio server exposing the review tool, backed by the web surface (ADR-0004). Bundled to dist/code-eye-mcp.mjs with npm run build.
• plugins/ — the Claude Code (plugins/claude-code/) and Codex (plugins/codex/) plugin wrappers: MCP server config + skills. The repo root doubles as a plugin marketplace for both hosts (.claude-plugin/marketplace.json, .agents/plugins/marketplace.json).
• index.ts — registers the /code-eye-web command and the review tool the agent can call.