← Back to blog

Why I Built an AI Code Auditor

·3 min read
aisecurityopen-sourceclaude

Updated October 2026: I rewrote the middle of this post. The first version described a design with several specialised agents, which is not what shipped. This is how the tool actually works.

The Problem

Every codebase has security issues. Most teams know this. Few do anything about it until it's too late.

Traditional static analysis tools catch the obvious stuff: hardcoded secrets, SQL injection patterns, missing auth checks. But they miss the subtle things. The business logic flaws. The race conditions in async code. The authentication bypass you'd only notice if you understood how three different modules interact.

I wanted to build something that thinks about security the way a senior engineer does. Not just pattern matching, but actually understanding the code.

Letting the Model Look

My first attempt was a single prompt. Build a digest of the codebase, send it to Claude, ask for vulnerabilities. It worked... kind of. The results were noisy and generic, because the model was guessing from a partial view. It couldn't open the file a suspicious import pointed to, so it inferred.

What fixed it was giving Claude tools instead of a summary:

  • list files to see how the project is laid out
  • search for a pattern across the repo
  • read a file, or a range of lines in it

All read-only, all locked to the project directory. Claude decides what to look at, follows a call from one module into the next, and has to submit findings with a file and line. There is a cap on turns and tokens so a run can't wander forever.

Before any of that, a set of plain static checks runs: hardcoded secrets, eval, SQL built by string concatenation, known-bad dependencies. They take milliseconds, need no API key, and give the model a starting point so it spends its time on the things patterns can't catch.

The single-prompt mode is still there as --fast, for when cheap and quick matters more than depth.

What I Learned

Building claude-audit taught me three things:

1. Evidence beats inference. The same model gives much better findings when it can go and read the code than when it is handed a digest and asked to guess. Tools mattered more than prompt wording.

2. Developer experience is the real product. Nobody cares how sophisticated your agent architecture is if the CLI is confusing. I spent more time on --help text, error messages and the report layout than on the agent loop.

3. Open source forces clarity. When strangers need to understand your code, you write better code. Every architectural decision gets pressure-tested by people with different assumptions.

Try It

npx claude-audit ./your-project

One command. Without an API key it runs the static checks only; with ANTHROPIC_API_KEY set, Claude does the full audit. Either way you get a score per category and a list of findings with file and line.

The source is at github.com/itsmesherry/claude-audit.