English · Русский
A local-first tool that finds useless comments in your source code
and removes them only with your consent.
Coding agents write code fast, and along with it comments like this one:
# Increment counter
counter += 1One such comment is harmless. A thousand of them are noise that buries the explanations that actually matter, adds dead lines to every diff, and creates an impression of documentation where there is none. Worst of all, the next AI-assisted edit multiplies the same text.
CommentRake finds comments like these and shows them next to the code they belong to. It runs on your machine: no account, no language model, and your source code never leaves the computer.
The tool does not treat comments as harmful in themselves. A stated reason, an invariant, a
description of a workaround, a TODO with context — that is exactly what comments are for.
CommentRake's job is to separate those from a retelling of the line below.
This is not a matter of taste; it is how the program is built. A rule that fires produces not an edit but a reason to look. Until a person has made a decision about a specific comment, no decision exists — the data model simply has no object for it.
Decisions differ, and none of them substitutes for another: remove the matched fragment, replace it, edit the comment by hand, or remove the comment entirely. A selected fragment is never widened to the whole comment on its own.
You need Python 3.12 or newer. The package is not released yet, so install it from source:
git clone https://github.com/kroxiksut/comment-rake.git
cd comment-rake
python -m pip install -e ".[cli,tui,gui]"Interfaces are installed as separate extras — take only the ones you will use:
| Extra | What it adds | Dependencies |
|---|---|---|
[cli] |
The commentrake command-line interface |
Typer, Rich |
[tui] |
The commentrake tui terminal interface |
Textual |
[gui] |
The commentrake gui desktop interface |
PySide6, Qt 6 |
The core, the parsing layer, and the rules depend only on tree-sitter,
tree-sitter-language-pack, and pathspec, and work without a single interface package.
Your first run is read-only and writes nothing at all:
commentrake scan .
commentrake scan . --format json --tests without-testsThe full cycle. Every step names the previous one explicitly, so you can only apply what has already been checked:
commentrake review . --format json
commentrake plan . --remove src/main.rs@0:18 --out approved-plan.json
commentrake dry-run . approved-plan.json
commentrake apply . approved-plan.json --state state.sqlite3 --confirm
commentrake archive list . --state state.sqlite3The writing steps — apply and restore — have not been exercised on real projects yet; see
project status. Everything before apply only reads files.
The same cycle from the keyboard, without memorising commands:
commentrake tui . --state state.sqlite3The desktop interface:
commentrake gui . --initialize-stateTo run straight from the repository without installing the package, use the helper scripts:
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-gui.ps1 . -InitializeStatesh scripts/run-gui.sh . --initialize-stateThe script adds only <repository>/src to PYTHONPATH, checks the Python version and the
required packages, and if they are missing asks where to install them: into a Conda environment,
into a local .venv, or into the current Python. Nothing is installed without a Y. The
initialisation flag is needed only on the first run — it grants explicit permission to create the
SQLite state in the user directory.
Open a code folder → Scan → Study the map or the list
→ Make decisions → EditPlan → Diff → Dry run
→ Apply → Archive and history snapshot
Before anything is applied you can see everything the change rests on: the comment itself, its kind, why the rule fired, the risk level, and the exact text that will end up in the file.
Scanning writes nothing — neither into the project nor into the history. Writing happens only at the last step, and only for an explicitly approved plan. In between, file fingerprints and range overlaps are validated: if a file changed after the scan, the old plan is rejected and a new scan is required rather than a write against stale offsets.
More detail: safe file editing.
Six deterministic rules, no language model involved: an empty or punctuation-only comment, an exact duplicate within the same file, a contentless heading, a restatement of the next action, step-by-step narration, and a boilerplate opening phrase.
Only the two safest are enabled by default — empty comments and exact duplicates. The rest are
enabled explicitly in commentrake.toml or by choosing an analysis profile. A profile decides
only which rules may report findings; it can never lift a protection.
Ordinary cleanup does not touch:
- documentation strings and comments;
TODO,FIXME,XXX,HACK,NOTE;- linter and formatter suppressions;
- compiler, type-checker, and coverage directives;
- generated-code markers;
- pragmas, the shebang line, encoding declarations;
- licence and copyright headers;
- inline comments;
- commented-out code.
These are distinct risk classes and they are handled differently — from "never propose by default" to "never remove". If parsing a file turned out to be uncertain, its comments can be inspected but not modified: there is no regex-based removal fallback behind the parser's back.
More detail: comment analysis and protected constructs.
The map answers "where should I look": where code, comments, and cleanup candidates are concentrated. In the desktop interface it is a radial diagram, in the terminal interface a proportional tree, and in the command-line interface a ranked summary plus JSON.
A real 983-file project: the sector angle is code volume, the outer ring is the selected secondary metric, and the panel on the right summarises the selected scope. The interface ships in English and Russian.
The list answers "what do I do with each case": search, sorting, filters, surrounding code, and the decisions themselves. Both views are built on one model with the same node identifiers and the same metrics, so moving between them never loses your place.
More detail: project map.
History, archive, and settings live in the user's CommentRake directory, separate from your project. Scanning, dry runs, and history keeping create no files and no directories inside the opened project. Logs contain no source code, no comment text, and no file paths.
Two exceptions happen only on an explicit command: commentrake.toml in the project root, a
shared team policy file meant for version control, and <project>/.commentrake/, if you would
rather keep local data next to the project. Neither appears on its own during a scan; for the
local directory the interface separately offers to add .commentrake/ to .gitignore.
There are no network features. If any ever appear, they will be opt-in.
| Interface | Built on | Used for |
|---|---|---|
| Desktop | PySide6, Qt 6 | Map, review list, code, diffs, archive, and history |
| Command line | Typer, Rich, JSON | Automation, CI, and coding agents |
| Terminal | Textual | The whole review sequence from the keyboard |
None of them carries its own copy of parsing, rules, metrics, or file writing — all of that lives in the core. The command-line text and its options are deliberately English; JSON is emitted as a single versioned document on stdout.
A separate non-blocking mode reviews changes before a commit: commentrake pre-commit . with
--mode staged, --mode working, or --mode range --range BASE..HEAD. It touches neither the
Git index, nor your sources, nor the history. More detail:
pre-commit review.
The first wave covers fifteen languages through Tree-sitter: Rust, C, C++, Python, JavaScript,
TypeScript, QML, HTML, CSS, XML, Shell, PowerShell, SQL, PostgreSQL, and T-SQL. Windows resource
templates (.rc, .rc.in) are handled separately, without a parser and without rules: there,
comments can only be inspected and selected by hand.
Grammars come from a local cache and are never downloaded during a scan. Every language ships with its own set of protected constructs and mandatory test fixtures.
| Area | What is used |
|---|---|
| Language | Python 3.12+ (development environment: 3.12.13) |
| Parsing | Tree-sitter |
| Interfaces | PySide6 with Qt 6, Typer with Rich, Textual |
| Storage | SQLite |
| Configuration | TOML |
| Checks | pytest, Ruff, mypy in strict mode |
Target platforms are Windows, Linux, and macOS. Reproducible environment setup is described in the environment document.
Pre-alpha. The tool already does real work, but nothing in it is frozen yet.
What is worth using today is everything that only reads files: visualising a project on the map, searching and filtering comments, parsing and classification, metrics, and comparing snapshots. All three interfaces work: command line, terminal, and desktop.
Editing code — the edit plan, diffs, dry run, apply, archive, and restore — is written and covered by tests, but it has not been exercised on real projects yet. Treat that part as unproven: work on a project under version control and read the diff before applying.
What is missing is a release. The package is installed from source and the version is
0.1.0.dev0. The commentrake.toml schema, the JSON report format, and the SQLite schema are
versioned, but they may still change before the first release. Some desktop mockups are approved
and some are not, and the corresponding screens are still being worked on.
Details are kept out of the README so that it stays readable. Every design document exists in both
languages: English under docs/en/, Russian under docs/ru/, and each one links to its twin.
- product concept;
- technical architecture;
- project map and navigation model;
- discovery, parsing, and comment classification;
- protected constructs per language;
- edit plan, apply, archive, and restore;
- threat model for the modifying operations;
- SQLite, snapshots, and historical analysis;
- cleanup statistics and the counting methodology;
- interface design and mockups;
- project configuration and the TOML schema;
- quality checks, regressions, and invariants;
- integration with coding agents;
- pre-commit review;
- development environment;
- development stages;
- guidance package for AI agents;
- documentation index.
The Russian documents are the originals: a change to one is made in both in the same edit. If the two ever disagree, the Russian text is the one that was written first, and the disagreement is a defect worth reporting.
Right now cases are more useful than code. A false positive on a real project, a comment that should never have been touched, an unusual source file, a compound extension — every such case becomes its own regression test and stays in the suite forever.
Next in usefulness: language adapters together with their protected constructs, testing on different platforms, navigation feedback, and translations. Before a substantial change, read the contribution guide and the architecture document.
Apache License 2.0. The full text is in the LICENSE file.
CommentRake is a rake for comments: walk the project, gather up the accumulated noise, and leave what is growing untouched.
The radial view of project structure was partly inspired by the disk-usage visualisation in Scanner by Steffen Gerlach. CommentRake borrows only the general principle of hierarchical navigation, no code and no assets from Scanner.
Your AI writes the comments. You decide which ones stay.