Skip to content
Back to search

critique

TUI & website for reviewing git changes

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/remorses--critique/badge.svg)](/listings/remorses--critique)

HTML

<a href="/listings/remorses--critique"><img src="/api/listings/remorses--critique/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

critique requires [Bun](https://bun.sh). It does not run under Node.js.

# Run directly without installing
bunx critique

# Or install globally
bun install -g critique

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 463 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align='center'>
  2. <br/>
  3. <br/>
  4. <h3>critique</h3>
  5. <p>Beautiful diff viewer for terminals, web previews, and agents.</p>
  6. <br/>
  7. <br/>
  8. </div>
  9. ![Diff Viewer Demo](screenshot.png)
  10. ## Installation
  11. critique requires [Bun](https://bun.sh). It does not run under Node.js.
  12. ```bash
  13. # Run directly without installing
  14. bunx critique
  15. # Or install globally
  16. bun install -g critique
  17. ```
  18. ## Quick Start
  19. Open the current working tree diff in the terminal:
  20. ```bash
  21. critique
  22. ```
  23. Upload the same diff and get a shareable URL:
  24. ```bash
  25. critique --web "Current working tree"
  26. ```
  27. Share a GitHub pull request directly, from any directory:
  28. ```bash
  29. critique https://github.com/remorses/sigillo/pull/19 --web "Sigillo PR #19"
  30. ```
  31. Review staged changes:
  32. ```bash
  33. critique --staged
  34. critique --staged --web "Staged changes"
  35. ```
  36. ## Core Diff Commands
  37. critique follows the same mental model as `git diff`.
  38. A GitHub PR URL fetches the pull request diff from the GitHub API. Public PRs work without login. For private PRs, use `gh auth login`, `GH_TOKEN`, or `GITHUB_TOKEN`. The URL also works with `--pdf`, `--image`, `--filter`, or in the terminal viewer.
  39. ```bash
  40. # View unstaged changes, including untracked files
  41. critique
  42. # View staged changes
  43. critique --staged
  44. # View changes since a ref
  45. critique HEAD~1
  46. critique main
  47. # View one commit only
  48. critique --commit HEAD~1
  49. critique --commit abc1234
  50. # Compare two refs, PR style
  51. critique main HEAD
  52. critique main feature-branch
  53. # Watch the working tree and refresh on changes
  54. critique --watch
  55. # Add experimental call-stack changes to the file tree
  56. critique --calldiff
  57. # Filter files by glob pattern
  58. critique --filter "src/**/*.ts"
  59. critique --filter "src/**/*.ts" --filter "lib/**/*.js"
  60. ```
  61. ## Which Commits a Diff Contains
  62. Whenever a diff spans commits, critique lists them before the diff or the URL.
  63. ```
  64. 3 commits, 22 files, +1573 -311
  65. 2a09302 Correct the identity docs, and mark the release minor
  66. 1fb8af7 Give every element a stable GPUI identity
  67. 7998490 Launch a window without stealing focus
  68. base: f948f50 Reclaim the style table when the tree shrinks
  69. + uncommitted working tree changes
  70. ```
  71. This matters because a **rebased branch can carry commits replayed from another
  72. branch**. The merge base is then too far back, and a shared link silently includes
  73. work you did not write. If a listed commit is not yours, pass the first commit of
  74. **your own work** as the base:
  75. ```bash
  76. # Wrong: the merge base pulls in a commit a rebase replayed onto the branch
  77. critique f948f50 --web "Element identity"
  78. # Right: start from your own first commit
  79. critique 7998490 --web "Element identity"
  80. ```
  81. Long ranges are truncated, but the **oldest commits are always kept**, because a rebase
  82. replays a foreign commit right above the base. Silence the list in scripts with
  83. `--no-commit-list`. With `--json` it goes to stderr and the commits are added to the
  84. JSON payload instead.
  85. ### Diverged Branches
  86. `critique A..B` and `critique <ref>` compare two trees directly. On **diverged**
  87. branches such a diff also **undoes** every commit that exists only on the base side.
  88. Those commits are part of the diff, so critique lists them too:
  89. ```
  90. 1 commit added, 1 commit reversed, 2 files, +1 -1
  91. added by right:
  92. a279fbe Only on right
  93. reversed from left:
  94. d395611 Only on left
  95. ! left and right have diverged, so this diff also undoes the commits above.
  96. ```
  97. `critique A...B` and `critique A B` start at the **merge base** instead, so they never
  98. reverse anything, and the `base:` line names the merge base rather than the ref.
  99. Plain unstaged and `--staged` diffs contain no commits, so nothing is printed.
  100. ## Call-stack Diffs
  101. `--calldiff` uses [calldiff](https://github.com/tanishqkancharla/calldiff) to show how function calls changed. Each changed call tree appears below its source file in the top file tree.
  102. ```bash
  103. # Working tree call changes
  104. critique --calldiff
  105. # Changes since a ref
  106. critique main --calldiff
  107. # PR-style comparison and web preview
  108. critique main HEAD --calldiff --web "Call flow changes"
  109. # One commit
  110. critique --commit HEAD --calldiff
  111. ```
  112. The feature is experimental. calldiff uses Tree-sitter and can install a language grammar through npm on first use. `--staged`, `--stdin`, and `--watch` are not supported with `--calldiff`.
  113. Set `CRITIQUE_CALLDIFF=1` to enable call-stack diffs by default:
  114. ```bash
  115. export CRITIQUE_CALLDIFF=1
  116. critique
  117. ```
  118. ## Navigation
  119. | Key | Action |
  120. | --- | --- |
  121. | `↑` / `↓` | Scroll up and down |
  122. | `p` | Open file selector dropdown |
  123. | `t` | Open theme picker |
  124. | `Option` held | Fast scroll at 10x speed |
  125. | `g` `g` / `G` | Jump to top / bottom |
  126. | `Ctrl+D` / `Ctrl+U` | Half page down / up |
  127. | `q` / `Esc` | Quit / close overlay |
  128. ## Web Previews
  129. `--web` renders the diff with the same terminal renderer, uploads it to [critique.work](https://critique.work), and prints a shareable URL.
  130. ```bash
  131. # Working tree changes
  132. critique --web "Fix auth retry"
  133. # Staged changes
  134. critique --staged --web "Release notes"
  135. # Changes since a ref
  136. critique main --web "Branch changes"
  137. # One commit
  138. critique --commit HEAD --web "Latest commit"
  139. # PR-style branch diff
  140. critique main HEAD --web "Current branch"
  141. # Pull request from GitHub (no checkout needed)
  142. critique https://github.com/remorses/sigillo/pull/19 --web "Sigillo PR #19"
  143. # JSON output for scripts
  144. critique --web "Deploy changes" --json
  145. ```
  146. Generated URLs look like `critique.work/v/<id>`.
  147. ![Web Preview](screenshot-web.png)
  148. ### Web Preview Options
  149. | Flag | Description | Default |
  150. | --- | --- | --- |
  151. | `--web [title]` | Generate and upload a web preview | `Critique Diff` |
  152. | `--staged` | Show staged changes | none |
  153. | `--commit <ref>` | Show changes from a specific commit | none |
  154. | `--calldiff` | Add experimental call-stack changes to the file tree | off |
  155. | `--cols <n>` | Desktop render width | `240` |
  156. | `--mobile-cols <n>` | Mobile render width | `100` |
  157. | `--filter <pattern>` | Filter files by glob, can be repeated | none |
  158. | `--theme <name>` | Use a fixed theme instead of auto light and dark mode | none |
  159. | `--no-commit-list` | Do not list the commits contained in the range | off |
  160. | `--open` | Open the URL in your browser | none |
  161. | `--json` | Print `{ url, id, curl, files, commits }` for scripts | none |
  162. | `--password <pw>` | Encrypt the link end to end with a password (or set `CRITIQUE_PASSWORD`) | none |
  163. ### Password Protected Links
  164. Add a **password** to encrypt the link end to end. The CLI encrypts the HTML and the patch on your machine before upload. critique.work only stores ciphertext and never receives the password, so **nobody but the people you give the password to can read the diff**. That includes me, the person who runs critique.work, and Cloudflare, which hosts it. Viewers type the password once and their browser decrypts.
  165. ```text
  166. your machine critique.work viewer's browser
  167. ──────────── ───────────── ────────────────
  168. diff ─► gzip ─► AES-256-GCM ───► stores ciphertext only ───────────► password ─► decrypt
  169. key = PBKDF2(password) no password, no key, no hash
  170. ```
  171. ```bash
  172. critique --web --password 'a long passphrase only you share'
  173. # or for every upload
  174. export CRITIQUE_PASSWORD='a long passphrase only you share'
  175. critique --web
  176. ```
  177. The browser remembers every password that worked, so one password unlocks all diffs you share with it. Protected links have no social preview image.
  178. Agents read the patch with **curl**. The CLI prints the command after upload. It sends a key that opens only this diff, never the password:
  179. ```bash
  180. curl -b 'critique_key=<key>' 'https://critique.work/v/<id>.patch'
  181. ```
  182. > [!WARNING]
  183. > Anyone who gets the encrypted upload can try to guess the password offline. Use 12 characters or more. A lost password cannot be recovered.
  184. ### How Web Uploads Work
  185. ```text
  186. ┌─────────────────────────────────────┐
  187. │ git diff / GitHub PR diff │
  188. └─────────────────────────────────────┘
  189. │
  190. ▼
  191. ┌─────────────────────────────────────┐
  192. │ opentui test renderer │
  193. └─────────────────────────────────────┘
  194. │
  195. ▼
  196. ┌─────────────────────────────────────┐
  197. │ HTML variants and raw patch │
  198. └─────────────────────────────────────┘
  199. │
  200. ▼
  201. ┌─────────────────────────────────────┐
  202. │ critique.work upload │
  203. └─────────────────────────────────────┘
  204. │
  205. ▼
  206. ┌─────────────────────────────────────┐
  207. │ shareable URL, optional .patch │
  208. └─────────────────────────────────────┘
  209. ```
  210. The CLI does **not** generate a local HTML file. It uploads to `critique.work`. Local HTML export is tracked separately in [issue #42](https://github.com/remorses/critique/issues/42).
  211. Uploaded diffs expire after 7 days unless you use a license key. Identical diffs reuse the same content hash URL.
  212. ### Privacy and Terms
  213. critique.work is run by Tommaso De Rossi ([remorses](https://github.com/remorses)). Anyone with a link can open a public diff, so do not upload secrets. Use `--password` when the operator of critique.work must not be able to read the diff either: password links are end-to-end encrypted. Delete an upload with `critique unpublish <url>`.
  214. - [Privacy policy](https://critique.work/privacy): what is stored, for how long, and how to delete it
  215. - [Terms of service](https://critique.work/terms)
  216. ## Raw Patch Access
  217. Every `--web` upload also stores the raw unified diff. Append `.patch` to any critique URL to fetch it.
  218. ```bash
  219. CRITIQUE_URL='https://critique.work/v/<id>'
  220. # View the patch in your terminal
  221. curl "$CRITIQUE_URL.patch"
  222. # Apply the patch directly to your repo
  223. curl -s "$CRITIQUE_URL.patch" | git apply
  224. # Reverse the patch
  225. curl -s "$CRITIQUE_URL.patch" | git apply --reverse
  226. ```
  227. ## Git Difftool Integration
  228. Configure critique as your git difftool:
  229. ```bash
  230. git config --global diff.tool critique
  231. git config --global difftool.critique.cmd 'critique difftool "$LOCAL" "$REMOTE"'
  232. ```
  233. Then run:
  234. ```bash
  235. git difftool HEAD~1
  236. ```
  237. ## Lazygit Integration
  238. Use critique as a custom pager in [lazygit](https://github.com/jesseduffield/lazygit):
  239. ```yaml
  240. # ~/.config/lazygit/config.yml
  241. git:
  242. pagers:
  243. - pager: critique --stdin
  244. ```
  245. For details, see [lazygit's Custom Pagers documentation](https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_Pagers.md).
  246. ## Pick Files from Another Branch
  247. `critique pick` lets you apply selected files from another branch to the current checkout.
  248. ```bash
  249. critique pick feature-branch
  250. ```
  251. Selected files are applied as patches. Deselected files are restored.
  252. ## Selective Hunk Staging
  253. `critique hunks` gives scripts and agents a stable alternative to `git add -p`.
  254. ```bash
  255. # List unstaged hunks with stable IDs
  256. critique hunks list
  257. # List staged hunks
  258. critique hunks list --staged
  259. # Filter by file pattern
  260. critique hunks list --filter "src/**/*.ts"
  261. # Stage one hunk by ID
  262. critique hunks add 'src/main.ts:@a1b2c3d4e5f6'
  263. # Stage multiple hunks
  264. critique hunks add 'src/main.ts:@a1b2c3d4e5f6' 'src/utils.ts:@f6e5d4c3b2a1'
  265. ```
  266. Hunk IDs use this format:
  267. ```text
  268. file:@<hash>
  269. file:@<hash>.1
  270. file:@<hash>.2
  271. ```
  272. The hash is from the hunk's added and removed lines, not the `@@` line numbers. Unrelated edits above or below the hunk do not change the ID. Duplicate payloads in the same file get `.1`, `.2`, and so on. Old `file:@-oldStart,...` IDs are no longer accepted.
  273. `critique hunks list` still prints the `@@` header under each ID, so you can see where the hunk sits in the file.
  274. ## E-Ink Reading
  275. Generate PDFs from diffs to read on Kindle or Boox e-readers.
  276. ```bash
  277. critique --pdf
  278. critique main --pdf --open
  279. ```
  280. The PDF preserves syntax highlighting and diff formatting. Email it to your Kindle, drop it in BooxDrop, or save it to a synced Google Drive folder. See [docs/e-reader-guide.md](docs/e-reader-guide.md) for setup details.
  281. ## Agent Skill
  282. This package ships a skill file that teaches AI coding agents how to use critique for diff URLs, PDFs, images, and selective hunk staging.
  283. ```bash
  284. npx -y skills add remorses/critique -g -y
  285. ```
  286. ## Features
  287. - **Syntax highlighting:** powered by [Tree-sitter](https://tree-sitter.github.io/) via [opentui](https://github.com/sst/opentui)
  288. - **Split view:** side-by-side comparison for wide terminals, unified view on narrow terminals
  289. - **Word-level diff:** highlights exact word changes inside modified lines
  290. - **File navigation:** quick file switcher with fuzzy search
  291. - **Click to open:** click line numbers to open in your editor with `REACT_EDITOR`
  292. - **Watch mode:** refreshes as you edit files
  293. - **Web previews:** hosted shareable URLs on [critique.work](https://critique.work)
  294. - **Raw patches:** every web preview has a `.patch` endpoint
  295. - **PDF output:** optimized for code review away from the terminal
  296. ## Supported Languages
  297. TypeScript, JavaScript, TSX, JSX, JSON, Markdown, HTML, CSS, Python, Rust, Go, Java, C, C++, C#, Ruby, PHP, Scala, Haskell, Julia, OCaml, Clojure, Swift, Nix, YAML, and Bash.
  298. ## Configuration
  299. | Environment Variable | Description | Default |
  300. | --- | --- | --- |
  301. | `REACT_EDITOR` | Editor command for click-to-open | `zed` |
  302. | `CRITIQUE_WORKER_URL` | Custom worker URL for web previews | `https://critique.work` |
  303. | `CRITIQUE_PASSWORD` | Password for every `--web` upload; `--password` overrides it | none |
  304. ## Ignored Files
  305. Lock files are automatically hidden from diffs:
  306. - `pnpm-lock.yaml`
  307. - `package-lock.json`
  308. - `yarn.lock`
  309. - `bun.lockb`
  310. - `bun.lock`
  311. - `Cargo.lock`
  312. - `poetry.lock`
  313. - `Gemfile.lock`
  314. - `composer.lock`
  315. Files with more than 6000 lines of diff are also hidden for performance.
  316. ## Built With
  317. - [opentui](https://github.com/sst/opentui): React-based terminal UI framework
  318. - [Tree-sitter](https://tree-sitter.github.io/): syntax highlighting
  319. - [diff](https://github.com/kpdecker/jsdiff): diff algorithm
  320. - [Hono](https://hono.dev/): web framework for the preview worker
  321. ## Sponsors
  322. <a href="https://coderabbit.link/remorses" target="_blank" rel="noopener noreferrer">
  323. <img src="https://github.com/coderabbitai.png" alt="CodeRabbit" height="24" />
  324. </a>
  325. Sponsored by [CodeRabbit](https://coderabbit.link/remorses).
  326. ## License
  327. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.