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
17 changes: 15 additions & 2 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,18 @@
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.6.0"
},
{
"name": "setup-trim-comments",
"source": "./",
"description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover.",
"strict": false,
"skills": [
"./skills/setup-trim-comments"
],
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.6.0"
},
{
"name": "trim-comments",
"source": "./",
Expand All @@ -132,7 +144,7 @@
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0",
"timeout": 300
}
]
Expand Down Expand Up @@ -167,6 +179,7 @@
"./skills/restate",
"./skills/session-eject",
"./skills/setup-agents-md",
"./skills/setup-trim-comments",
"./skills/trim-comments",
"./skills/wait-for-action"
],
Expand All @@ -179,7 +192,7 @@
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0",
"timeout": 300
}
]
Expand Down
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.6.0"
},
{
"name": "setup-trim-comments",
"source": "./skills/setup-trim-comments",
"description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover.",
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.6.0"
},
{
"name": "trim-comments",
"source": "./skills/trim-comments",
Expand Down Expand Up @@ -113,6 +121,7 @@
"./restate",
"./session-eject",
"./setup-agents-md",
"./setup-trim-comments",
"./trim-comments",
"./wait-for-action"
]
Expand Down
17 changes: 15 additions & 2 deletions .github/plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,18 @@
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.6.0"
},
{
"name": "setup-trim-comments",
"source": "./",
"description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover.",
"strict": false,
"skills": [
"./skills/setup-trim-comments"
],
"category": "workflow",
"homepage": "https://github.com/killallgit/killall-skills",
"version": "5.6.0"
},
{
"name": "trim-comments",
"source": "./",
Expand All @@ -133,7 +145,7 @@
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0",
"timeout": 300
}
]
Expand Down Expand Up @@ -168,6 +180,7 @@
"./skills/restate",
"./skills/session-eject",
"./skills/setup-agents-md",
"./skills/setup-trim-comments",
"./skills/trim-comments",
"./skills/wait-for-action"
],
Expand All @@ -180,7 +193,7 @@
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0",
"timeout": 300
}
]
Expand Down
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,3 +175,17 @@ prints the `bd create` commands for an epic plus one bead per candidate, which
it runs only for the candidates you pick. It keeps `GLOSSARY.md`,
`ARCHITECTURE.md`, and `docs/adr/` current as decisions land. Words after the
command name a direction. User-invoked only.

## Trim comments

The `trim-comments` plugin hook runs on every Stop in Claude Code. It finds the
comments and docstrings in the files the session edited, in any repo, plus every
uncommitted or untracked file in the repo the session started in, including work
that predates the session. A reviewer on a different model deletes the ones the code
already says. The reviewer may edit only the flagged files, and an edit that changes
code is restored; outside Python, a `#` line inside a multi-line string (a YAML block
scalar, a heredoc) reads as a comment and can be removed.
It acts only in repos that opt in with a `.commentrc` at the root, and it needs
`uv` and the `claude` CLI. `/setup-trim-comments` surveys a repo and writes that file;
`/trim-comments` runs the trimmer by hand. See `skills/trim-comments/SKILL.md` for
the config keys and the exact checks. Both are user-invoked only.
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",
"./setup-trim-comments",
"./trim-comments",
"./wait-for-action"
]
Expand Down
4 changes: 4 additions & 0 deletions skills/setup-trim-comments/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"name": "setup-trim-comments",
"description": "Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover."
}
64 changes: 64 additions & 0 deletions skills/setup-trim-comments/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
name: setup-trim-comments
description: Define a project's .commentrc for trim-comments by surveying the repo and asking which directories and extensions to cover.
disable-model-invocation: true
---

# Set up trim-comments

Write the project's `.commentrc`: the file that opts a repo into the
`trim-comments` hook and sets its `include`, `exclude` and `extensions`. Work
from the repo root, which must be a git repository. When a `caveman` skill is
available in this session, invoke it first.

The survey is the `trim-comments` script. It sits next to this skill, in
`../trim-comments/scripts/trim_comments.py`, and needs `trim-comments` installed.
When that path is missing, stop and tell the user to install `trim-comments`
beside this skill.

## 1. Survey

Run `uv run --python 3.12 <skill-dir>/../trim-comments/scripts/trim_comments.py --survey`
from the repo root. When `.commentrc` exists, read it too: its keys are the
starting answers, and the survey already applies them.

Done when you can say which directories hold the project's own code, which hold
vendored, fixture or example code, and which suffixes are `unsupported`. The
extension counts cover every tracked file, and the list stops at the top 15.

## 2. Decide

Ask one question per decision the survey leaves open, with a recommended option
first. Skip a decision the survey settles.

- **`include`**: the top-level directories to cover, such as `src`. Recommend the
ones holding the project's own code. Omit `include` when the code spans the whole tree.
- **`exclude`**: the conventional directories present (`tests`, `fixtures`,
`migrations`, `examples`), tool and agent config directories (`.claude`,
`.agents`, `.beads`), and anything else vendored. Tests are the user's call: an
agent writes restating comments there too.
- **`extensions`**: each `unsupported` suffix with many files, mapped to `hash`
(`#` comments) or `slash` (`//` and `/* */`). Leave out suffixes whose comment
syntax is neither.

Generated files with a `do not edit` header are skipped already; leave them out
of `exclude`.

## 3. Write

Write `.commentrc` at the repo root as JSON. A new file holds only the keys that
differ from the defaults, and `{}` enables the defaults. An existing file keeps
every key this run did not change, even one equal to a default. In `exclude`, write a directory as a
plain name (`tests`) to match it at any depth, or as a path (`src/gen`) to anchor it at
the repo root. In `include`, plain names are anchored at the repo root (`src`); use
`**/lib` for any depth. A glob such as `**/migrations/**` works in both, with `*`
staying within a directory and `**` crossing them.

## 4. Verify

Run the survey again. Done when it prints no `bad config`, the per-directory
counts match what the user chose, and each excluded conventional directory has left
the `conventional directories present` list. Fix the file and rerun until they do.

End with the file's contents and one line: commit `.commentrc` so teammates and
worktrees inherit it.
5 changes: 5 additions & 0 deletions skills/setup-trim-comments/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
interface:
display_name: "Set up trim-comments"
short_description: "Write a project's .commentrc by surveying the repo and asking what to cover."
policy:
allow_implicit_invocation: false
47 changes: 34 additions & 13 deletions skills/trim-comments/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,36 +15,49 @@ 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
started in, which catches changes made through Bash. Uncommitted work that
predates the session is in this set too, so its comments are reviewed.

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:
Requires `uv` and the `claude` CLI on `PATH`. 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.
`--survey` prints, under the current `.commentrc`, the repo's most common extensions
(top 15, counted over every tracked file), the reviewable files per top-level
directory, the generated-file count and the conventional directories present.
`/setup-trim-comments` uses it to write the `.commentrc`.

## 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`.
- The reviewer runs through `claude -p` with `Read` and `Edit` only, no MCP
servers, no user, project or local settings, and `dontAsk` permissions. `Edit` is allowed on the flagged files by
path and denied everywhere else. A file whose path holds `* ? [ ] { } ( ) !` is
skipped, because those characters read as permission patterns.
- 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.
- The check runs when the reviewer fails or times out too. An unsafe edit is rolled
back; a deletion that passes is kept, and the file is retried on the next Stop.
- Files the reviewer changes outside the flagged set are restored, and a file it
creates is deleted. The summary line names them.
- Everything the hook discards is copied into the git dir's
`trim-comments-rejected` folder first.
- 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.
heredoc) reads as a comment and can be removed. The check cannot tell it apart.
- The hook fails open. A reviewer error, a timeout or a missing `uv` or `claude`
shows a warning or does nothing, and never blocks the session. While the
reviewer runs the Stop waits, for up to 5 minutes.
- 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.*`.
Expand All @@ -62,8 +75,8 @@ nothing there; an empty file enables the defaults. Every key is optional:

```json
{
"include": ["src/**"],
"exclude": ["**/migrations/**", "tests/**"],
"include": ["src"],
"exclude": ["**/migrations/**", "tests"],
"extensions": {".vue": "slash"}
}
```
Expand All @@ -72,8 +85,16 @@ nothing there; an empty file enables the defaults. Every key is optional:
- `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 `exclude` name without a slash (`tests`, `*.snap.py`) matches at any depth, like
gitignore, and covers everything under a directory of that name. A path with a slash
(`src/gen`) and every `include` entry (`src`) is anchored at the repo root; write
`**/lib` to include `lib` at any depth.
- 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.
## Hosts

Plugin installs register the hook on Claude Code, where it is tested. The hook
command finds the script under `${CLAUDE_PLUGIN_ROOT}` in either plugin layout, and
does nothing when the variable is unset or the script is missing, so a host that
loads the hook file without that layout stays quiet. Other hosts are untested.
`npx skills add` installs skills only, so the hook never runs there.
2 changes: 1 addition & 1 deletion skills/trim-comments/hooks/hooks.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"hooks": [
{
"type": "command",
"command": "[ -z \"${CLAUDE_PLUGIN_ROOT}\" ] || uv run --python 3.12 \"${CLAUDE_PLUGIN_ROOT}/skills/trim-comments/scripts/trim_comments.py\"",
"command": "R=\"${CLAUDE_PLUGIN_ROOT}\"; for S in \"$R/skills/trim-comments/scripts/trim_comments.py\" \"$R/scripts/trim_comments.py\"; do if [ -f \"$S\" ] && command -v uv >/dev/null; then exec uv run --python 3.12 \"$S\"; fi; done; exit 0",
"timeout": 300
}
]
Expand Down
Loading
Loading