I install a lot of small tools. A CLI from someone's GitHub, a Homebrew tap with twelve stars, a Rust binary that does one thing well. This is how I like software, and there has never been more of it.

Unless it’s a really established project, with many eyes on it, it’s a leap of faith. How do I know what the code actually does?

In theory, I could review it. But let’s be realistic, no one is fluent enough in every programming language, and no one has the time to carefully review the code of every tool they want to try; at least not me.

README is a claim

Every decent repo has a README, and the README file is a claim. The code is the fact.

A tool that says "renames files based on EXIF data" has no business making network calls, reading ~/.ssh, or spawning subprocesses. If it does, you don't need threat modeling or a CVE database. You've found it. Most malicious code reveals itself exactly at the point where behavior exceeds stated purpose.

So the question becomes: does the capability stay inside the claimed scope? A tool claiming LAN-only sync should have no HTTP client and no hardcoded external hosts. A tool claiming "offline, no telemetry" should have zero outbound capability, full stop. The narrower the claim, the sharper the check — and a violated narrow claim is the strongest finding you can get.

This is the kind of task LLM agents happen to be good at. They're patient, they read every file, and they don't get bored on line 400. Grep the dependency manifest, check every network call, decode every base64 blob, read every if that branches on the current date. It's mechanical.

The audit-repo skill

So I wrote a skill that does exactly this. It's structured around the README-vs-code principle rather than a generic checklist:

1. Establish the claim. Confirm the repo is the one you meant (not a typosquat), record the exact commit hash, and write down in one sentence what the project says it does — including any scope limits it declares for itself ("offline", "LAN-only", "read-only").
2. Read the code against that claim. Network activity, filesystem access outside the working directory, environment scraping, dynamic execution, persistence (cron, systemd, .zshrc, LaunchAgents), obfuscation, self-downloading payloads. Then the ones a grep alone misses: credential-store access, clipboard and screen capture, environment fingerprinting, time-gated behavior, covert exfiltration through a channel that looks legitimate, unsafe deserialization, insecure randomness for secrets, hardcoded backdoor conditionals.
3. Check the dependencies. Typosquats, wide-open version ranges, git-URL deps, and above all install-time scripts — postinstall runs before any other part of your review matters.
4. Sandbox anyway. A clean read is not a guarantee.

It also records positive findings: stripping setuid bits from received files, redacting secrets by default, atomic writes. Deliberate defensive choices tell you something about the author.

The output is a short prose report — findings, verdict, and a reliability note kept separate from the malice verdict, because a tool can be perfectly honest and still eat your files.

Finally, a report card: a color-coded label, one row per category, styled after the privacy nutrition labels on app stores, except each row is graded against the stated claim rather than scored in isolation. Green means "matches the claim or absent". Red means "undisclosed, or contradicts the claim". You can read it in three seconds.

Get the code-security-review skill from github.com/vrypan/skills. Install it and next time, before you install a cool new tool, ask your AI agent "perform a security review of https://...".