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.
• declutter notes add — let a coding agent hand you its review findings as draft notes; nothing is posted until you've opened each one.

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.

brew install nikolajmosbaek/tap/declutter     # or: 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.

Notes from a coding agent

An agent that reviews the PR can hand you its findings as notes, for you to read, edit or drop before anything is posted:

declutter notes add pr 42 --path src/cart.ts --line 13 --text "A 100% discount is allowed"
declutter notes add pr 42 --json findings.json   # [{"path", "line", "side": "old", "text"}, …]
declutter notes add pr 42 --text "Nothing tests the new branch"   # on the PR, not a line

A note has to sit on a line of the diff (the error says which lines are); --json adds all of its notes or, if any is refused, none. A second note on a line goes under the first. These notes are drafts: marked as such in the viewer and never posted until you open one with m (or P) and press Enter — edited or not. Emptying a note deletes it.

Afterwards, declutter notes pr 42 --json shows what is still pending and what was posted, with a link to each comment, so the agent can see which findings you kept. declutter notes post pr 42 posts without opening the viewer (--yes skips the question; drafts still stay).

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

brew install nikolajmosbaek/tap/declutter                  # macOS and Linux, with Homebrew
curl -LsSf https://github.com/NikolajMosbaek/declutter-diff/releases/latest/download/declutter-diff-installer.sh | sh
cargo binstall declutter-diff                              # a ready-made binary, with cargo-binstall
cargo install declutter-diff                               # build it yourself (needs Rust)

All four install the declutter command. Ready-made binaries are on the releases page for macOS (Apple silicon and Intel) and Linux (x86-64 and ARM).

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 -n                               # print with each row's old and new line numbers
declutter notes [<target>] [--json]        # the notes as a prompt (or JSON), of one review or all
declutter notes add <target> …             # add draft notes, e.g. from a coding agent
declutter notes post <target> [--yes]      # post a PR's notes without opening the viewer
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>/ — base and head, plus merge when the host publishes one, so git rev-parse refs/declutter/pr/42/head tells you which commit was reviewed; 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 (drafts left out) 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 (declutter notes <target> one review's) 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; on GitHub, one review via gh api — or, if GitHub refuses it, one comment per note, on the file when GitHub won't take that line), as whoever those CLIs are signed in as. Drafts you haven't opened are kept back. Posted notes move to .git/declutter/posted.jsonl with a link to where they landed; 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