io.github.BenAHammondPublished by GitHub account BenAHammondv5.0.2Updated Oct 24, 2026
Enforces architectural invariants and code quality rules inside your AI agent's edit loop.
Code Auditor MCP exposes rule lookup, symptom explanation and install help for a code-auditing tool that enforces project invariants inside an AI agent's edit…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.BenAHammond%2Fcode-auditor-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"code-auditor": {
"type": "http",
"url": "https://www.codeauditormcp.com/api/mcp"
}
}
}Architectural invariants enforced inside your AI agent's edit loop. When the agent writes code that breaks a project rule, Code Auditor catches it and blocks the edit. The agent sees the rule's message and fixes itself.
Two commands to install everywhere. code-audit install --agent all copies the skill to every AI coding tool on your machine. Use --agent for specific tools.
What you get per tool: the skill (SKILL.md), MCP server access, and hook wiring where the tool supports it (blocking on Claude Code and Codex, advisory on Cursor).
Claude Code users can also install via plugin:
The hook auto-installs the auditor on first use via npx.
node:sqlite module, so nothing needs to compile or
download a prebuilt binary on install.better-sqlite3, an
optional dependency whose install script must be approved once on npm
11.2+/12 (they block dependency install scripts by default):
npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3
(with pnpm: pnpm approve-builds, then select better-sqlite3).Project-level settings live in .codeauditor.json (invariant rules, analyzer settings, and thresholds). Eleven environment variables additionally tune process-scoped behavior — worker pool size, daemon and job-queue timeouts, the index location, the SQLite backend, and the UI port.
When CODE_AUDITOR_DATA_DIR is set, the index is scoped per project (<dir>/projects/<sha256(root)[:16]>/index.db) so projects can't leak data into each other. When unset, the index lives in a user-level OS cache (<os_cache>/code-auditor/projects/<hash>/index.db) so it never lands inside the audited repo.
"Index the codebase and run a full audit, then walk the violations file-by-file with code-audit next-file."
"Create a .codeauditor.json that bans lodash imports and prevents src/languages/ from importing anything in src/analyzers/."
"Run a full audit, fix the highest-priority file, and repeat code-audit next-file until the tree is clean."
"Sync the code index and audit only what changed vs main."
"Add an ast-pattern rule that blocks new Function(...)."
"Add a naming rule requiring hooks in src/hooks/ to start with use."
"Add a call-constraint so chargeCustomer() in src/services/payment.ts can only be called from src/api/."
Seven kinds. The agent writes them to .codeauditor.json. Bad configs fail the audit, not silently.
One skill, one CLI, one MCP server. Every agent gets the same audit engine — the hook contract is the only difference.
MCP config generation covers a wider set than skill install. The MCP server's generate tool writes a client config file for any of claude, codex, cursor, gemini, copilot, continue, awsq (AWS Q Developer), codeium (Codeium/Windsurf), vscode, cline, and zcode. Four of those — Continue, AWS Q Developer, Codeium/Windsurf, and Cline — are MCP-only: they have no file-based skill or hook path, so they connect through the generate tool rather than code-audit install.
Hook behavior: Blocking means the diff-scoped changed gate is tripped — an invariant rule that declares gating: true (a binary, per-rule flag, independent of severity) blocks the edit from landing (the agent sees the violation and fixes inline). Advisory means violations are reported through the strongest available feedback channel but the edit has already occurred. Cursor's afterFileEdit hook is fire-and-forget with no output consumption. MCP is available everywhere for shell-less use.
Code Auditor's built-in rules fall into two categories:
Deterministic rules ship at critical or severe. Advisory rules ship at severe or high. Rules proven near-zero precision on a real corpus are disabled by default (off) — users opt in when the rule matches their domain.
Built-in severity defaults are recalibrated from real-corpus triage. The current defaults reflect measurement on three corpora: this tool's own codebase, Gin, and Excalidraw. Six data-access rules that produced near-zero precision across all three corpora are disabled by default.
Every disabled rule documents what corpus it would be useful on. Users can restore any rule via severityOverrides in .codeauditor.json:
Severity overrides apply globally (before per-directory path profile caps). Setting a rule to "off" removes it from the output entirely.
The sql-injection-risk rule is disabled by default (off) after recalibration. On the self-audit corpus, it produced 0% precision — the rule misinterpreted TypeScript pattern-matching code (string constants like 'SELECT', 'FROM', 'WHERE' used for the tool's own SQL detection) as database queries. On the Gin and Excalidraw corpora, precision was also near zero.
When to re-enable it: your project's SQL is constructed via string concatenation or template literals in functions whose sole purpose is query assembly. The rule detects those patterns. For codebases using ORMs or parameterized queries exclusively, the rule produces noise.
To re-enable and block on SQL injection:
With sql-injection-risk: critical (and the rule marked gating), your agent's hook will block edits that introduce AST-level SQL injection patterns.
Every finding is a measurement, not a verdict — but measurements are occasionally wrong. When the agent hits a false positive (the rule is right in general, wrong for this specific code), it can dismiss that one instance rather than work around it:
The <fingerprint> comes from the JSON report (every violation carries a fingerprint field). A written --reason is required, and the dismissal clears exactly one finding — rule + file + symbol — so the same rule still fires everywhere else. Dismissals live in a committed .codeauditor.dismissals.json, reviewable in a diff.
The reason an agent gives for dismissing a finding is the most useful signal for improving the rules. Code Auditor can send dismissed findings to an anonymous feedback service that collects them.
It is off by default and turned on only by an explicit opt-in, via any of three methods (in precedence order):
code-audit dismiss --telemetry … sends just that one dismissal; --no-telemetry suppresses one.CODE_AUDITOR_TELEMETRY=1 (or 0) as a machine-level default for headless/CI runs.code-audit telemetry status|enable|disable (or the telemetry MCP tool), which records the choice in your user config dir.telemetry enable needs no arguments: it opts in against the built-in service endpoint (overridable for self-hosting). Opting in generates an anonymous install ID: a random value generated locally, never derived from your machine, user, or project, used only to group submissions by source.
What is sent — the tool version, the rule ID, the urgency level, the dismissal reason exactly as typed, a structural AST signature (grammar kinds only, never their contents), a coarse language hint, a timestamp, and the anonymous install ID. What is never sent — source code, identifiers, literals, file paths, or anything derived from your code or environment. Sending is best-effort: offline or an unreachable endpoint is silent and never blocks an edit or fails a gate.
Code Auditor indexes every style declaration in your project — CSS, SCSS, Tailwind, inline styles, and CSS-in-JS. The styles rules read global distributions and flag fragmentation that no single-file linter can see.
7 detectors, 10 rule IDs:
The styles rules read from a project-wide SQLite index, so scoped runs (changed files only) still compare against the full project baseline. A fresh #273828 drift color in a scoped run is caught against the full corpus of #1e2328 values.
Style invariant rules:
Style search operators — search by property, value, mechanism, or token:
The React rules also gain raw-element detection: if your project has a Button wrapper, raw <button> usages outside Button's definition become severe findings.
MIT
Source: README.md at commit b792894
Get Install Commands
Return the exact install commands for Code Auditor for a given AI agent. Call this when a user asks how to install Code Auditor, or asks for the command for a specific agent (claude, cursor, codex, gemini, agents, zcode, or all).
agentrequiredLook Up Rule
Return the rule kind, description, default severity, detection method, and threshold for a given Code Auditor rule or analyzer. Call this when a user asks what a specific rule does (e.g. import-ban, sql-injection, n+1).
rule_idrequiredExplain Symptom
Map a natural-language symptom (e.g. 'my app is slow', 'hardcoded password', 'infinite react loop') to the relevant Code Auditor rule(s) and their fixes. Call this when a user describes a problem rather than naming a rule.
symptomrequiredRequest Rule
Request a new Code Auditor rule. Call lookup_rule or explain_symptom first to confirm no existing rule covers it. Provide a minimal example that should be flagged and a corrected example that should not. Reduce both to the smallest code that shows the difference, and remove secrets and proprietary identifiers. Returns a receipt id.
titlerequiredsignalrequiredsymptomrequiredlanguagesrequiredtoolVersioncleanExamplerequiredfiringExamplerequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
npm install -g code-auditor-mcpcode-audit install --agent allcode-audit install --list # see the support matrixclaude plugin marketplace add BenAHammond/code-auditor-mcpclaude plugin install code-auditor{ "severityOverrides": { "sql-injection-risk": "critical", "missing-org-filter": "severe", "loop-query": "severe" }}{ "severityOverrides": { "sql-injection-risk": "critical" }}code-audit dismiss <fingerprint> --reason "generated code, not hand-written"{ "rules": [ { "kind": "style-mechanism", "message": "Only Tailwind in src/components/", "allow": ["tailwind"], "path": "src/components/**" }, { "kind": "no-raw-values", "message": "No raw colors in src/pages/ — use design tokens", "properties": ["color", "background-color"], "path": "src/pages/**" } ]}code-audit search "css:margin-top value:16px" # specific valuecode-audit search "mechanism:inline css:color" # inline color declarationscode-audit search "token:--color-primary" # bypassing a design token