# code-eye

Evidence-backed, local-first AI code review for CLI coding agents — [pi](https://pi.dev), 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:

![Web review: agent walkthrough notes inline on the diff](docs/assets/web-review.png)

## 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

```bash
pi install npm:@toddzheng024/code-eye
```

Or from the git repo:

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

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

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

To try it without installing:

```bash
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:

```toml
[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.

![Web review: per-commit view with file stats, status chips, and expandable gaps](docs/assets/web-review-commit.png)

- 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

```bash
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:

```bash
pi -e ./index.ts
```

Or symlink it for auto-discovery and hot reload:

```bash
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.