Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 40 additions & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,31 @@
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0"
},
{
"name": "trim-comments",
"source": "./",
"description": "Run the comment trimmer by hand on the files changed in this checkout. On Claude Code the plugin also runs it on every Stop.",
"strict": false,
"skills": [
"./skills/trim-comments"
],
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0",
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"timeout": 300
}
]
}
]
}
},
{
"name": "wait-for-action",
"source": "./",
Expand Down Expand Up @@ -142,11 +167,25 @@
"./skills/restate",
"./skills/session-eject",
"./skills/setup-agents-md",
"./skills/trim-comments",
"./skills/wait-for-action"
],
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0"
"version": "5.5.0",
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"timeout": 300
}
]
}
]
}
}
]
}
9 changes: 9 additions & 0 deletions .cursor-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,14 @@
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0"
},
{
"name": "trim-comments",
"source": "./skills/trim-comments",
"description": "Run the comment trimmer by hand on the files changed in this checkout. On Claude Code the plugin also runs it on every Stop.",
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0"
},
{
"name": "wait-for-action",
"source": "./skills/wait-for-action",
Expand All @@ -105,6 +113,7 @@
"./restate",
"./session-eject",
"./setup-agents-md",
"./trim-comments",
"./wait-for-action"
]
}
Expand Down
41 changes: 40 additions & 1 deletion .github/plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,31 @@
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0"
},
{
"name": "trim-comments",
"source": "./",
"description": "Run the comment trimmer by hand on the files changed in this checkout. On Claude Code the plugin also runs it on every Stop.",
"strict": false,
"skills": [
"./skills/trim-comments"
],
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0",
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"timeout": 300
}
]
}
]
}
},
{
"name": "wait-for-action",
"source": "./",
Expand Down Expand Up @@ -143,11 +168,25 @@
"./skills/restate",
"./skills/session-eject",
"./skills/setup-agents-md",
"./skills/trim-comments",
"./skills/wait-for-action"
],
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.5.0"
"version": "5.5.0",
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"timeout": 300
}
]
}
]
}
}
]
}
2 changes: 1 addition & 1 deletion pytest.ini
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
[pytest]
pythonpath = scripts skills/wait-for-action/scripts skills/architectural-review/scripts
pythonpath = scripts skills/wait-for-action/scripts skills/architectural-review/scripts skills/trim-comments/scripts
testpaths = tests
1 change: 1 addition & 0 deletions skills/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
"./restate",
"./session-eject",
"./setup-agents-md",
"./trim-comments",
"./wait-for-action"
]
}
4 changes: 4 additions & 0 deletions skills/trim-comments/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"name": "trim-comments",
"description": "Run the comment trimmer by hand on the files changed in this checkout. On Claude Code the plugin also runs it on every Stop."
}
79 changes: 79 additions & 0 deletions skills/trim-comments/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
name: trim-comments
description: Run the comment trimmer by hand on the files changed in this checkout. On Claude Code the plugin also runs it on every Stop.
disable-model-invocation: true
---

# Trim comments

A Stop hook finds the comments in the files the session edited and hands them
to a reviewer on a different model. The reviewer deletes each comment whose
information the code already carries and keeps the ones that record why.

Files come from two sources, each grouped by the git repo that holds it:

- every file the transcript shows an `Edit`, `Write`, `MultiEdit` or
`NotebookEdit` touching, in any repo
- every file changed since `HEAD` (plus untracked) in the repo the session
started in, which catches changes made through Bash

Each repo is reviewed under its own `.commentrc`, with `cwd` set to that repo.
Edits made by subagents are not in the parent transcript; the second source is
the only thing that sees them, and only in the session's own repo.

Run it by hand from the checkout to review:

```bash
uv run --python 3.12 <skill-dir>/scripts/trim_comments.py
```

`--dry-run` prints the flagged comments and the reviewer prompt without calling it.

## Fixed behavior

- The reviewer is `haiku`, or `sonnet` when the working agent ran on haiku, read
from the session transcript. `TRIM_COMMENTS_MODEL` overrides it.
- The reviewer gets `Read` and `Edit` only (`--tools`, no MCP servers), through `claude -p`.
- Shebangs, license headers, common lint, type and tooling directives, and PEP 723
script blocks never reach the reviewer.
- A reviewed file is checked after the edit and restored byte for byte when it
fails: Python must keep the same syntax tree apart from docstrings, and other
files may only lose comment lines or comment tails.
- Files the reviewer changes outside the flagged set are restored too, and a file
it creates is deleted. The summary line names them.
- Outside Python, a `#` line inside a multi-line string (a YAML block scalar, a
heredoc) reads as a comment and can be removed.
- The hook fails open. A reviewer that errors or times out shows a warning and
never blocks the session.
- Only files with a known extension are read, and only outside the default
excludes: `node_modules`, `vendor`, `dist`, `build`, `.venv`, `venv`,
`__pycache__`, `*.min.*`, `*_pb2.py`, `*.generated.*`.
- Files whose first five lines say `do not edit`, `@generated`, `code generated` or
`auto-generated` are skipped.
- Styles: `python` (`tokenize` for `#`, `ast` for docstrings; a docstring that is
a body's only statement is skipped), `hash` (`.sh .bash .zsh .yml .yaml .toml
.rb .tf`), `slash` (`//` and `/* */` in `.js .jsx .ts .tsx .go .rs .java .c
.cc .cpp .h .hpp .swift .kt`).

## Scope

A repo opts in by having a `.commentrc` at its root. Without one the hook does
nothing there; an empty file enables the defaults. Every key is optional:

```json
{
"include": ["src/**"],
"exclude": ["**/migrations/**", "tests/**"],
"extensions": {".vue": "slash"}
}
```

- `include`: when present, only matching paths are reviewed.
- `exclude`: added to the default excludes.
- `extensions`: maps a suffix to a style, adding it or overriding a default.
- Globs match repo-relative paths: `*` stays within a directory, `**` crosses them.
- An invalid config shows a warning and skips the run.

Plugin installs register the hook on Claude Code. A host that does not set
`CLAUDE_PLUGIN_ROOT` runs the hook command as a no-op. `npx skills add` installs skills only, so
the hook never runs there.
5 changes: 5 additions & 0 deletions skills/trim-comments/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
interface:
display_name: "Trim comments"
short_description: "Have a second model delete comments that only restate the code."
policy:
allow_implicit_invocation: false
15 changes: 15 additions & 0 deletions skills/trim-comments/hooks/hooks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"timeout": 300
}
]
}
]
}
}
Loading
Loading