Skimless

Skimless

[CI] [npm] [License: MIT]

English · Português

The reading order for pull requests that got too big.

Skimless turns a diff into a packet: what to read first, which files can wait, and which lines deserve a human. It runs on your machine. It does not call a model, post a comment, or phone home.

Zero runtime dependencies. Node.js 22 or newer. A CLI, a GitHub Action, a library, and an MCP server for AI agents. Packets in English and Portuguese.

npx skimless demo

[A Skimless review packet: headline, stats, and the reading order]

skimless  Do not skim this one14 files · +86 −8 · about 2 min. 5 high-priority findings.First pass: index.ts, fixture.ts, verify.ts.
 1  src/api/index.ts                  Public export changed 2  src/webhooks/fixture.ts           Secret-shaped string added 3  src/webhooks/verify.ts            Signature compared with == 4  .github/workflows/release.yml     Workflow grants write permissions 5  src/billing/invoice.ts            Billing path changed 6  test/webhooks/verify.test.ts      Test file deleted 7  migrations/2026_09_23_api_keys.sql 8  src/billing/charge.ts 9  package.json                      Dependency manifest changed10  Dockerfile11  test/billing/charge.test.ts       Can wait12  docs/webhooks.md                  Can wait13  package-lock.json                 Can wait14  src/generated/types.ts            Can wait

The sample verify.ts calls timingSafeEqual on a buffer compared with itself. Skimless has no rule for that. It puts the file third, under the live-shaped key, so a person sees it. That is the product: a path through the diff, not a verdict.

English packet · Pacote em português · A real diff: Express 4.21.2 → 5.0.0

Why this exists

Pull requests written with an agent get big. The reviewer opens the first file, gets tired, and approves the lockfile with the same glance they would give a migration. Skimless tells you where skimming is safe and where it is not: the public API first, the sharp edges next, the noise at the end. The score is a reading priority. A quiet packet does not prove the diff is safe.

Run it

npx skimless demonpx skimless demo --lang pt --format html --out skimless.htmlnpx skimless review --base origin/main --format all --out skimless --fail-on high

Or install it once with npm install -g skimless and call skimless.

--format all writes skimless.html, skimless.md, and skimless.json. Secret-shaped strings are redacted unless you pass --no-redact. --fail-on defaults to none locally. In CI, use high.

On a generated 2,000-file diff, a review packet comes back in about 100 ms on a laptop. npm run bench prints the number for your machine.

import { redactPacket, reviewDiff } from "skimless";
const packet = redactPacket(reviewDiff(patch, { order: "story", lang: "pt", budgetMinutes: 25 }));packet.readingOrder.forEach((stop) => console.log(stop.path, stop.reason));

What the packet is

• A reading order. story is the default: API and types, then auth, signing, billing, migrations, and CI, then manifests, then the rest, then tests, docs, lockfiles, and generated code. A high finding jumps its file up into the sharp band. risk sorts by score alone.
• Findings with the rule id attached. Twenty-one rules, each one a sentence, covering JavaScript, TypeScript, Python, Ruby, Go, PHP, Java, Kotlin, Rust, and C#, plus GitHub Actions, GitLab CI, and other runners. See docs/rules.md.
• An HTML file you can attach, a Markdown comment, and JSON for whatever you already run.

Copy examples/skimless.config.json to skimless.config.json to set the budget, ignore globs, and the CI failure level.

CI

- uses: actions/checkout@v4  with:    fetch-depth: 0- uses: pedroofrancaa/skimless@v1  with:    base: origin/${{ github.base_ref }}    fail-on: high

The action needs no token and posts no comment. The reading order and findings land in the job summary, on the pull request's Checks page. It passes inputs through the environment, then to git diff as arguments, never stitched into a shell string. docs/ci.md has the full workflow, every input, and a GitLab CI job.

Use it from an agent

skimless mcp is an MCP server. Claude Code, Cursor, VS Code, and other agents can ask for the reading order before they review a change, then read the files in that order.

claude mcp add skimless -- npx -y skimless mcp

Skimless still does not call a model. It serves one. Secret-shaped strings are always redacted in MCP responses, so a live key in the diff never reaches the agent's context. docs/mcp.md has the setup for each client, the tool arguments, and prompts that work.

What it will not do

• It will not execute the diff.
• It will not call a model, and it will not pretend a heuristic is one. Agents can call Skimless; Skimless does not call them.
• It will not catch every bug. The self-compare in the sample is the example we keep on purpose.
• A quiet label is not an approval.

Development

npm installnpm testnpm run checknode --experimental-strip-types src/cli.ts demo

Day to day, the CLI runs the TypeScript source directly. npm run build emits dist/, which is what npm ships.

Rules, reading order, and the library surface are described in docs/. The contributor notes are in CONTRIBUTING.md. The project is MIT, in GOVERNANCE.md terms: one maintainer at the start, decisions in the open, no pretended community.

License

MIT