Skip to content
/
Tier A A8 Cross-runtime harness

crit

crit-review · tomasz-tomczyk/crit · ★ 350 · last commit 2026-05-23

Primitive shape 4 total
Commands 1 Skills 2 Hooks 1
00

Summary

crit — Summary

Crit is a browser-based code review UI for AI agent output (binary: crit, Go, MIT license, crit.md hosted SaaS + self-hostable). It surfaces agent-generated plans, code diffs, live running apps, and static HTML previews in a GitHub PR-style browser interface where the human can leave inline comments pinned to specific lines; the agent then reads the structured JSON review file and acts on unresolved comments. The key design principle: comments persist across rounds, round-to-round diffs show exactly what changed, and unresolved threads stay open until explicitly resolved — unlike /review slash commands that dump one-time prose. It ships a Claude Code plugin (1 hook on PermissionRequest/ExitPlanMode + 2 skills: crit and crit-cli) plus install scripts for 13 other AI tools (Cursor, Copilot, Codex, OpenCode, Gemini, Qwen, Hermes, Windsurf, Cline, Grok, Aider, Pi). The local binary binds to 127.0.0.1 with zero telemetry; sharing is opt-in and uploads to crit.md or a self-hosted crit-web instance. Weekly releases based on user feedback.

Differs from seeds: No seed has a comparable human-review UI surface. Closest in philosophy to kiro (Archetype 5: closed IDE with review surfaces and spec-phase tooling), but crit is agent-agnostic, local-first, and not an IDE fork. Compared to spec-kit (Archetype 2: structured review via files + hooks), crit adds a browser rendering layer on top of the file-based review artifact. The human-in-loop UI with persistent line-pinned comments and round-to-round diffs is architecturally absent from all 11 seeds.

01

Overview

crit — Origin, Philosophy, and Manifesto

Origin

Built by Tomasz Tomczyk, staff engineer. From the README:

"I review a lot of agent output. When I started using AI agents full-time, the code generation was impressive — but I was spending more time re-reading terminal diffs than the agent spent writing the code. I kept missing things that a proper review surface would have caught in seconds. So I built Crit."

GitHub: tomasz-tomczyk/crit. MIT license. Go language. 350 stars, 16 contributors. Active (last commit 2026-05-23, weekly releases). Website: crit.md (Phoenix LiveView + Fly.io).

Core Philosophy

From the FAQ section of crit.md:

"Why this over just asking the agent to review?" Because the agent reviewing its own output is the thing you're trying to escape. Crit puts you back in the loop. You see the lines, you point at them, the agent responds to specific feedback — not your fuzzy recollection of what you wanted.

"Why this over a /review slash command?" Slash commands review once and dump prose. Crit gives you a persistent surface: comments stay attached to lines across rounds, round-to-round diffs show what actually changed, and unresolved threads stay unresolved until you say so.

"Why a browser at all?" Because line-precise feedback on a 600-line plan is miserable in a terminal. Markdown rendering. Syntax highlighting. Click-and-drag selection. Same shape as a GitHub PR, no GitHub round-trip.

Design Principles

  1. Local-first: server binds to 127.0.0.1, zero telemetry, no account required for local use
  2. Single binary: no dependencies, no config needed to start
  3. Any-agent: "Every agent reads files. That's the whole protocol." Review file is plain JSON; any agent that can read a file can use it
  4. Persistent comments: unresolved threads stay open across rounds — not one-shot

Modes (Four review surfaces)

  • Plans & docs: renders markdown in browser, per-section comments
  • Code: auto-detects branch diffs, syntax-highlighted, inline PR-style comments
  • Live: proxies running dev server, comments pinned to DOM elements
  • Preview: renders static HTML artifacts in iframe with element comments
02

Architecture

crit — Architecture, Distribution, and Installation

Distribution

  • CLI binary: Go single binary, available via Homebrew, Go install, Nix, Windows
  • Claude Code plugin: claude plugin install crit@crit (marketplace: tomasz-tomczyk/crit)
  • 13 other agent integrations: crit install cursor|codex|gemini|windsurf|cline|...
  • SaaS sharing: crit.md (Phoenix LiveView, Fly.io) — optional, for sharing reviews
  • Self-hostable: crit-web repo (deploy your own backend)

Version analyzed: latest from GitHub (commit 1042671c, 2026-05-23)

Installation

brew install crit
# or
go install github.com/tomasz-tomczyk/crit@latest
# or
curl binary download from GitHub Releases

# Claude Code plugin
claude plugin marketplace add tomasz-tomczyk/crit
claude plugin install crit@crit

Directory Tree

tomasz-tomczyk/crit/
├── integrations/           # per-agent integration files
│   ├── claude-code/
│   │   ├── .claude-plugin/
│   │   ├── hooks/
│   │   │   └── hooks.json  # PermissionRequest/ExitPlanMode hook
│   │   └── skills/
│   │       ├── crit/SKILL.md        # main review skill
│   │       └── crit-cli/SKILL.md    # CLI wrapper skill
│   ├── cursor/
│   ├── codex/
│   ├── gemini/
│   ├── aider/
│   ├── windsurf/
│   ├── cline/
│   ├── opencode/
│   ├── github-copilot/
│   └── ... (13 total)
├── frontend/               # browser UI (Phoenix LiveView components)
├── *.go                    # Go source (plans, diff, proxy, share, session, etc.)
├── main.go
└── go.mod

Config Files

  • ~/.crit.config.json — user-level CLI configuration
  • ~/.crit/reviews/ — review data (per-branch, not in repo)

Required Runtime

  • Go binary (no runtime deps) for local use
  • For sharing: internet access to crit.md or self-hosted crit-web

Version Control Support

Git, jj (Jujutsu), Sapling — auto-detected.

Target AI Tools

Claude Code (plugin), Cursor, GitHub Copilot, OpenCode, Codex, Gemini, Qwen, Hermes, Windsurf, Cline, Grok, Aider, Pi — any agent that can read a file and run a shell command.

03

Components

crit — Components

CLI Commands

crit                              # auto-detect changed files (branch diff mode)
crit plan.md                      # review a specific file (plans/docs mode)
crit plan.md api-spec.md          # review multiple files
crit http://localhost:3000        # review running dev server (live proxy mode)
crit landing.html                 # review static HTML (preview mode)
crit --pr <num|url>               # GitHub PR review
crit --range <base>..<head>       # commit range

crit status                       # show review file path and daemon status
crit cleanup                      # delete stale review files
crit comment src/auth.go:42 'msg' # programmatic inline comment (for agents)
crit comment src/handler.go:15-28 'msg'
crit share                        # share review to crit.md
crit install <agent>              # install agent integration
crit plan-hook                    # invoked by ExitPlanMode hook
crit auth login|logout|whoami    # crit.md account management

Claude Code Plugin Components

Hook: PermissionRequest/ExitPlanMode

{
  "hooks": {
    "PermissionRequest": [{
      "matcher": "ExitPlanMode",
      "hooks": [{
        "type": "command",
        "command": "crit plan-hook",
        "timeout": 345600
      }]
    }]
  }
}

Intercepts plan mode exit. Forces a crit review before the agent proceeds past planning. Timeout of 345600 seconds (4 days) — allows for async human review.

Skill: crit (main review skill)

Manages the full review loop: launch crit in background → wait for "Finish Review" → read structured JSON review file → act on unresolved comments.

Key directives:

  • Launches crit as a background task via run_in_background: true
  • Relays browser URL to user verbatim
  • Blocks until crit completes (human clicks "Finish Review")
  • Reads structured JSON output; acts on all resolved: false comments
  • Supports quote (selected text), anchor (current position), drifted: true (stale line numbers)

Skill: crit-cli (programmatic comment skill)

Lower-level skill for agents to add comments without opening the browser UI.

Review File Format

JSON with three comment types:

  • review_comments (top-level, r_-prefixed IDs) — general feedback
  • Per-file comments (no start_line/end_line) — about the file as a whole
  • Line comments (with start_line/end_line, optional quote, anchor, drifted) — pinned to specific lines

Browser UI Features

  • Round-to-round split/unified diff
  • Per-line and range comments (click or drag)
  • Vim keybindings (j/k/c/Shift+F)
  • Draft autosave
  • Live file watching (auto-reload on source change)
  • Concurrent reviews (each instance on its own port)
  • Syntax highlighting with per-line comment support inside code fences
  • Per-branch review isolation (~/.crit/reviews/ keyed by branch)
05

Prompts

crit — Prompt Files and Techniques

Prompt 1: crit SKILL.md — Blocking Wait Instruction (Mandatory Gate pattern)

## Step 2: Launch crit and block until review completes

**CRITICAL — you MUST run this step. Do NOT skip it. Do NOT proceed without it.**

Run `crit` **in the background** using `run_in_background: true`:

```bash
crit <plan-file>   # specific file
crit               # git mode

If a crit server is already running from earlier in this conversation, crit automatically connects to it. Starting from scratch, it spawns the daemon, opens the browser, and blocks until the user clicks "Finish Review".

crit prints the review URL on startup (e.g. Started crit daemon at http://localhost:<port>). Relay it verbatim:

"Crit is open at http://localhost:. Leave inline comments, then click Finish Review."

Do NOT proceed until crit completes. Do NOT ask the user to type anything. Do NOT read the review file early. Wait for the background task to finish — that is how you know the human is done reviewing.


**Technique**: Mandatory Gate with explicit prohibitions. The skill uses `**CRITICAL**` emphasis, negative imperatives ("Do NOT"), and explicit reasoning ("that is how you know the human is done reviewing"). This is a blocking human-in-loop gate expressed entirely in prompt language. The background task execution model (`run_in_background: true`) is the mechanism; the prompt text is the guardrail preventing the agent from proceeding past it.

## Prompt 2: crit SKILL.md — Auto-detect Context (Context-aware routing)

```markdown
## Step 1: Pass arguments to `crit`

The CLI auto-detects the review mode from its arguments. **Do not ask the user which mode to use.** Pass `$ARGUMENTS` through:

If no arguments, check conversation context:

1. A plan file was written earlier in this conversation → `crit <plan-file>`
2. Otherwise → bare `crit` (branch diff)

Technique: Inference over clarification. "Do not ask the user which mode to use" is an explicit anti-question instruction. The skill provides a decision tree (conversation context scan) so the agent can resolve mode selection without user prompting.

Prompt 3: crit SKILL.md — Drifted Comment Handling (Defensive state-reading)

<important if="a comment has a quote, anchor, or drifted field">
- `quote`: the specific text the reviewer selected — focus your changes on the quoted text rather than the entire line range
- `anchor`: use it to locate the current position of the content; line numbers may be stale after edits
- `drifted: true`: original content was removed or heavily rewritten — line numbers are approximate at best

Technique: Conditional instruction block with if attribute on an <important> tag. This is a structured prompt pattern that activates only when specific JSON fields are present in the review data. The drifted: true handling addresses a real failure mode in multi-round reviews where line numbers become stale after intermediate edits.

09

Uniqueness

crit — Uniqueness and Positioning

Differs from Seeds

No seed has a human-in-loop browser review UI. The closest philosophical parallel is kiro (Archetype 5: structured review surfaces with explicit approval gates), but kiro is an IDE fork with proprietary primitives, while crit is a local-first binary that works with any agent via file protocol. Among code-review seeds, spec-kit (Archetype 2: structured review hooks) uses file-based review artifacts and PostToolUse hooks for review enforcement, but lacks the browser rendering and persistent comment model. Crit is architecturally closest to GitHub's PR review surface, but local and synchronous with the agent rather than requiring a remote GitHub round-trip. The ExitPlanMode hook integration with Claude Code's permission system is architecturally unique in this corpus — it's the only framework that hooks into plan-mode exit as a mandatory review gate.

Positioning

Crit occupies the human-review-as-a-gate position in the agent workflow. Most frameworks in this corpus focus on automating away human review; Crit embraces and improves the human review step. The browser UI, round-to-round diffs, and persistent comment threads solve the concrete usability problem: reviewing AI-generated plans/code in a terminal is genuinely unpleasant, and line-reference feedback is error-prone in chat.

The "any agent" protocol (plain JSON file + crit comment CLI) is a deliberate architectural choice. By having no SDK dependency, crit achieves near-universal compatibility across 13+ agent integrations while letting each integration do its own agent-specific skill file.

Observable Failure Modes

  1. Plan-mode hook timeout abuse: The ExitPlanMode hook has a 4-day timeout. In CI or unattended mode, this blocks indefinitely unless the hook is bypassed.
  2. Browser dependency: All review modes require a browser. Server-only or headless environments can't use the primary review surface.
  3. Stale line numbers: The drifted: true mechanism handles stale comments after multi-round edits, but large rewrites can break all existing comment anchors.
  4. Closed SaaS sharing: Sharing requires crit.md account or self-hosted crit-web. The CLI is MIT but the sharing backend is a hosted service.
  5. No LLM validation: Crit doesn't validate that the agent actually addressed the comments — it only reads resolved: false state. An agent could mark comments resolved without making changes.

Explicit Antipatterns

  • Agent reviewing its own output instead of human (FAQ: "the agent reviewing its own output is the thing you're trying to escape")
  • One-shot prose-dump review (slash commands that "review once and dump prose")
  • GitHub round-trip for local review feedback
04

Workflow

crit — Workflow

Primary Workflow: /crit Slash Command Loop

Phase What happens Artifact
1. Agent completes work Plan written or code changes made plan file or git diff
2. /crit activated Agent runs crit <file> or crit (background) daemon started
3. Browser opens Crit renders review surface at localhost:PORT —
4. Agent relays URL "Crit is open at http://localhost:PORT. Leave inline comments, then click Finish Review." —
5. Human reviews Leaves per-line comments in browser review.json updated
6. Human clicks "Finish Review" Crit completes, prints review file path review.json
7. Agent reads review.json Identifies all resolved: false comments comment list
8. Agent acts on comments Fixes issues per feedback code/plan changes
9. Agent re-runs /crit Round-to-round diff shows changes updated browser view
10. Iterate until resolved All threads marked resolved —

Plan Mode Hook Workflow (Claude Code)

Phase What happens
Agent in plan mode Drafts plan
Agent exits plan mode ExitPlanMode event fires
Hook intercepts crit plan-hook launches
Browser opens for plan review Human reviews plan before execution begins
Timeout: 4 days Allows async review across sessions

Approval Gates

  1. "Finish Review" button: explicit human action required to unblock agent
  2. ExitPlanMode hook: automatic gate — agent cannot proceed past planning without completing crit review (when hook is active)
  3. Unresolved comment threads: agent must address all resolved: false comments before considering work done

Round Tracking

Each round of agent edits creates a new snapshot. The browser shows round-to-round diffs. Comments from previous rounds that are not yet resolved persist to the new round. drifted: true flag marks comments where the original content was removed or rewritten.

06

Memory Context

crit — Memory and Context

Review File as Persistent State

The review.json file (~/.crit/reviews/<branch>/review.json) is the primary state artifact. It persists across:

  • Browser refreshes
  • Agent session context resets
  • Multiple rounds of edits

Comments have resolved boolean state that persists until explicitly changed. This makes the review file a durable human-annotation store.

Per-branch Isolation

Review data is keyed per branch (~/.crit/reviews/). Switching branches preserves each branch's independent review state. Review data lives outside the repo (no git commits).

Round Snapshots

round_snapshots.go — each round of agent edits creates a snapshot. The browser diff view computes the delta between consecutive snapshots. Snapshots are stored locally.

Draft Autosave

Browser drafts autosave — closing mid-review preserves the draft state.

Session State

session.go, session_focus.go — daemon session management. Daemon persists across multiple crit invocations within a session (subsequent crit calls connect to the existing daemon rather than spawning a new one).

Cross-session Handoff

Partial: review.json persists across sessions, so unresolved comments from a previous session are visible in the next. Daemon does not persist across terminal sessions.

Sharing (Optional)

crit share — uploads to crit.md or self-hosted crit-web. Generates a shareable URL. Sharing is opt-in and explicit; local mode has zero telemetry.

07

Orchestration

crit — Orchestration

Multi-agent

No. Crit is a single-agent review tool. It mediates between one human reviewer and one AI agent. No subagents.

Orchestration Pattern

Sequential. Agent works → human reviews → agent addresses → repeat.

Isolation Mechanism

None for the agent. The review surface (browser UI) is isolated from the agent's working directory (review data in ~/.crit/, not in the repo).

Execution Mode

Event-driven. The ExitPlanMode hook fires when the agent attempts to exit plan mode. The crit skill fires when invoked by the human or by another skill.

Concurrency

Multiple crit instances can run simultaneously on different ports for reviewing multiple plans or codebases concurrently.

Multi-model

Not applicable — crit does not make LLM calls. It is a review surface that mediates between human and agent.

Human-in-Loop

Explicit blocking human gate. The browser "Finish Review" button is the only mechanism to unblock the agent. The SKILL.md explicitly states: "Do NOT proceed until crit completes."

08

Ui Cli Surface

crit — UI and CLI Surface

Dedicated CLI Binary

Yes. Binary name: crit. Written in Go. Single binary, no dependencies.

CLI Design

Positional arguments dispatch to modes (auto-detected by argument type). Named subcommands for utility operations. Agent-friendly crit comment for programmatic comment injection.

Browser UI (Primary surface)

Local web UI served by the crit daemon at 127.0.0.1:PORT. Browser opens automatically when crit starts.

Features:

  • Round-to-round split/unified diff toggle
  • Inline line and range comments (click line number, drag to select range)
  • Comment rendering inline after referenced lines (GitHub PR style)
  • Syntax highlighting with per-line comment support inside code fences
  • Vim keybindings: j/k (navigate), c (comment), Shift+F (finish), ? (help)
  • Draft autosave
  • Live file watching (auto-reload)
  • Concurrent reviews on separate ports
  • DOM-pinned comments for live proxy mode
  • Element comments for static HTML preview mode

Review Modes

  • Plans & docs: crit plan.md — markdown render with section/line comments
  • Code: crit (no args) — branch diff, syntax highlighted, PR-style
  • Live: crit http://localhost:3000 — running app proxied into review surface
  • Preview: crit landing.html — static HTML in iframe

Self-Hosting

crit-web (separate repo) — Phoenix LiveView backend that can be deployed for sharing reviews across teams. CRIT_SHARE_URL env var points the CLI at the custom instance.

SaaS Tier (crit.md)

Hosted sharing service. Free account via GitHub OAuth. Sharing is opt-in; local use is entirely free and zero-telemetry.

CI/CD

No CI integration. Review happens in the human-agent loop, not in automated pipelines.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.