declutter

Read the code, not the commentary.

AI agents write diffs where the logic hides under doc blocks that repeat the function name, a comment above every line, a log call in every branch, tests twice the size of the change and a formatter's worth of whitespace. declutter is a terminal diff viewer that peels those layers off, one key each, so you review what the code does first — and the rest when you choose to.

• c — comments gone, even the ones trailing a line of code, along with the blank lines they brought.
• C — only the comments: check what the AI claims against what it wrote.
• t i l f — tests, imports, logging and whitespace-only changes, hidden or alone.
• declutter <PR URL> — review a GitHub or Azure DevOps pull request, leave notes on lines, and post them as review comments when you quit.

It parses the code with tree-sitter, so a // inside a string stays code, every line number points at the real file, and the status line always says what is hidden.

Languages: Swift, TypeScript/TSX, JavaScript, Python, Go, Rust and Kotlin — see Supported languages. Any other file still gets the tests and formatting layers and moved-code detection.

cargo install declutter-diff
declutter                    # the branch you're on, against main

What it looks like

An AI-written change to a small cart module, everything shown — the way a plain diff reads:

The same change with comments and logging hidden (c, l): only the code is left, with a review note (m) on the line that needs a decision:

Comments only (C) — check what the AI claims its code does, on its own:

? lists every key:

The pictures are drawn by the viewer itself — see Development to redraw them.

Review pull requests in one line

Copy the pull request's URL from the browser and hand it to declutter:

declutter https://github.com/acme/shop/pull/42
declutter https://dev.azure.com/contoso/Mobile/_git/shop/pullrequest/1234
declutter pr 42                  # just the number, for the repository you're in

That's the whole setup. declutter fetches the PR — no branch to check out, nothing of yours touched — and shows exactly the diff the PR page shows, layers and all. Leave notes with m as you go; when you quit, it lists them and asks:

You left 1 note in this review:
  `src/cart.ts:13`  Should a 100% discount be allowed?
Post 1 comment to PR 42? [y/N] y
Posted 1 comment to PR 42.

Each note lands on its line in the PR, posted under your own account:

The recording uses a pretend acme/shop served from a local repository — see docs/pr.tape.

Nothing is posted unless you answer y; notes you don't post are kept for next time.

Layers

Five layers, each shown, hidden or shown on its own:

• Comments: line and block comments and doc comments (Python docstrings, Rust ///, KDoc, Go doc comments) in every supported language.
• Tests: whole test files, by the usual conventions in any language — Tests/, FooTests/, __tests__/, src/test/, FooTests.swift, FooTest.kt, foo.test.ts, test_foo.py, foo_test.go — or by importing a test framework (XCTest, Testing, Quick, pytest, unittest, vitest, jest, JUnit, kotlin.test, Kotest). Inside Rust source files, #[cfg(test)] modules and #[test] functions are test blocks of their own: hiding tests cuts them out, only tests keeps just them.
• Imports: import statements and export … from re-exports, Go import blocks, Rust use and extern crate, Kotlin import.
• Logging: statements that only log — print, NSLog, os_log, console.*, Go's fmt.Print*/log.Print*/slog, Rust's println!/dbg!/log/tracing macros, Kotlin's println, Android Log.* and Timber — and debug/info/warn/error/… calls on any logger. Calls that do more than log stay code: fmt.Fprintf (it may write a response) and log.Fatal (it ends the program).
• Formatting: changes that only move whitespace — re-indenting, re-spacing, re-wrapping a statement over more or fewer lines, added blank lines. When hidden, the new layout stays visible as context. Indentation counts as code in Python and in files without a grammar.

Supported languages

Formatting-only changes and moved code are found in every file, whatever the language. In a file without a grammar, nothing else is hidden and indentation is treated as code.

Adding a language takes its tree-sitter grammar and a few rules in src/lang.rs and src/classify.rs; issues asking for one are welcome.

Install

cargo install declutter-diff   # installs the `declutter` command

Or from a clone: cargo build --release, then use target/release/declutter. Needs Rust 1.90 or newer. Reviewing pull requests uses git's own access to the remote; posting notes uses the az (Azure DevOps) or gh (GitHub) CLI.

The design, the decisions behind it and the roadmap are in prod.md.

Use

Run inside a git repository:

declutter                                  # the branch you're on vs main, uncommitted work included
declutter <PR URL>                         # a GitHub or Azure DevOps pull request
declutter pr 42                            # PR 42 of the repository origin points at
declutter feature/login                    # a branch vs main, from where it split off
declutter feature/login --base develop     # … vs another branch
declutter --base develop                   # the branch you're on vs develop
declutter HEAD                             # only your uncommitted work
declutter main...feature                   # any range, as in git diff
declutter HEAD~3                           # a revision vs the working tree
declutter --staged                         # HEAD vs the index
declutter --print                          # print instead of opening the viewer
declutter -p --comments only               # print only the comment changes
declutter --tests hidden                   # start with test files left out

• Pull requests — paste the URL from the browser. The PR is fetched into refs/declutter/pr/<n>/ (no local branch is created or moved) and shown as the PR page shows it. It is read from the merge ref both hosts publish, so all it needs is git's own access to the remote; only when there is no merge ref (a conflicting or closed PR) does it ask the gh or az CLI for the branches.
• No arguments — on a branch, everything it changes: its commits since it split off from the main branch plus whatever isn't committed yet, untracked files included. On the main branch itself (or a detached HEAD) it shows just the uncommitted work.
• Branches — a local branch, or one on origin (fetched first if you don't have it yet), is compared with the main branch: what origin/HEAD points at, else main or master. --base picks another. Naming the main branch itself, or any other revision, compares it with your working tree.

The file list's title says what is being compared (origin/main...feature/login, PR 42).

Viewer keys:

Toggling a layer keeps the cursor on the same line of the file (or the closest one still shown), so you can flip comments on and off without losing your place.

Layers combine: everything set to hidden is cut out together. A layer set to only wins — with comments on only you see just the comment changes, whatever else is hidden.

Moved code (M collapses). A block of three or more lines removed in one place and added in another — same file or a different one, re-indented or not — is drawn in its own tint with a marker (⇄ 14 lines moved to Checkout.swift:173) at each end, in the viewer and in --print.

The status line always says what is hidden, e.g. comments: hidden · tests: hidden · showing 7 of 12 hunks · 5 comment-only hunks hidden · 4 test files hidden.

Review marks are saved per repository in .git/declutter/reviewed.tsv (shared by worktrees, never committed). A mark belongs to the exact change, so a file you reviewed shows up unreviewed again as soon as a new commit touches it.

Notes belong to the review they were left in — a pull request, or a range such as origin/main...feature — and only show up there. They are kept in .git/declutter/notes.json. E copies the review's notes as a prompt ("Please address these review comments… 1. path:line: note") and also saves it to .git/declutter/review-notes.md; declutter notes prints every note and declutter notes --clear deletes them.

Posting notes to the pull request. When you quit a review of a PR, declutter lists the notes you left and asks Post 3 comments to PR 42? [y/N]. Only y posts: each note becomes a comment on its line (a thread in Azure DevOps via az rest, a review comment on GitHub via gh api, on the file when GitHub won't take that line), as whoever those CLIs are signed in as. Posted notes leave the local store; any that fail stay, with the error.

o knows the line syntax of VS Code (and Cursor/Windsurf), Sublime, Zed, Helix, Vim/Neovim, nano, Emacs, micro, Xcode (xed) and JetBrains IDEs; terminal editors take over the screen until you quit them. With no editor set it uses the system opener. It opens the working-tree file, which is the reviewed version unless you're reviewing an older range.

Development

cargo test                       # the whole suite (113 tests), under 10 seconds once built
cargo test --test navigation     # one area (file names below)
cargo test brackets              # tests whose name contains "brackets"
cargo clippy --all-targets       # lint; kept at zero warnings

The suite runs offline and touches nothing outside a temporary directory. It needs nothing but git on your PATH:

• Git fixtures — repositories are built per test in temp directories, with your global git config switched off, so they behave the same on every machine.
• Pull requests — a local repository plays GitHub (a fake github.com/acme/shop reached through git's insteadOf), with the PR published as a merge ref, the way the hosts publish it. The gh/az lookup and the comment posting are swapped for stubs: no test talks to GitHub or Azure DevOps.
• The viewer — drawn into an in-memory terminal (ratatui's TestBackend), then checked cell by cell: text, colours, the cursor, what a key press changes.

What each test file covers:

Most behaviours were checked the other way round too: break the code, see the test fail.

The README's pictures are made from the same code — cargo run --example demo redraws the screenshots and vhs docs/demo.tape / vhs docs/pr.tape re-record the animations (brew install vhs).

License

MIT