Open source — MIT licensed. Built to be self-hosted and auditable.
Architectural invariants enforced inside your AI agent's edit loop
Two commands to install everywhere:
npm install -g code-auditor-mcpcode-audit install --agent allCopies the skill to every AI coding tool on your machine. Use --agent for specific tools.
Get the skill, hook wiring (blocking on Claude Code and Codex, advisory on Cursor), and MCP server.
code-audit install --list to see the support matrix.
One skill, one CLI, one MCP server. Every agent gets the same audit engine — the hook contract is the only difference.
Find this skill on registries:
Install from skills.sh: npx skills add BenAHammond/code-auditor-mcp
Hook behavior: Blocking means violations at or above --fail-on severity prevent 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.
The agent edits code. The hook audits the diff. Violations are caught before they reach your repo.
Claude edits or writes a file in your codebase.
PostToolUse hook runs on every Edit/Write. Only the changed files are audited.
Code Auditor checks invariant rules + analyzers. Exit code 2 on violations.
The agent sees the rule message, fixes inline, and the loop continues.
Seven rule kinds. The agent writes them to .codeauditor.json. Bad configs fail the audit, not silently.
Banned module imports
Ban `lodash` imports — use native instead
Function calls from unauthorized files
`chargeCustomer()` only callable from `src/api/`
Imports across module boundaries
`src/languages/` can't import from `src/analyzers/`
Exported symbols not matching a pattern
Hooks in `src/hooks/` must start with `use`
AST nodes matching an ast-grep pattern
Ban `new Function(...)` — eval by another name
Unapproved style mechanisms per file/glob
Only Tailwind in `src/components/` — inline styles banned
Hardcoded values for specific CSS properties
No raw hex colors — use design tokens (`var(--...)`)
Example .codeauditor.json
{
"rules": [
{
"id": "no-lodash",
"kind": "import-ban",
"severity": "critical",
"module": "lodash",
"message": "Use native Array/Object methods instead of lodash"
},
{
"id": "no-new-function",
"kind": "ast-pattern",
"severity": "critical",
"pattern": "new Function($$$)",
"message": "new Function() is eval by another name"
},
{
"id": "tailwind-only",
"kind": "style-mechanism",
"severity": "warning",
"allow": ["tailwind"],
"path": "src/components/**",
"message": "Only Tailwind in src/components/"
},
{
"id": "no-raw-colors",
"kind": "no-raw-values",
"severity": "warning",
"properties": ["color", "background-color"],
"path": "src/pages/**",
"message": "Use design tokens, not raw hex"
}
]
}TypeScript, JavaScript, Go, and CSS/SCSS. Powered by tree-sitter WASM grammars — zero native compilation.
Thirteen analyzers, one audit — across TypeScript, JavaScript, Go, and CSS/SCSS. Each runs against every changed file the moment your agent edits — violations are caught before they reach the repo.
Architectural integrity checks — the five principles that keep a codebase maintainable as it scales.
Functions and classes that do too much — detected by counting public methods, analyzing cohesion, and flagging multi-concern names like doEverything or handleAllTheThings.
How it's measured
Method count per class, responsibility keyword heuristics, architectural layer detection
Threshold
Class with > 12 public methods or serving multiple architectural layers
Code that resists extension — long if-else chains, switch statements on types, and instanceof checks that grow unbounded with every new case.
How it's measured
AST pattern matching for type-switching patterns, instanceof cascades, enum-based branching
Threshold
> 3 branches in a type-dispatching conditional
Subclasses that weaken their parent's contract — throwing NotImplementedError, tightening parameter types, or strengthening return types.
How it's measured
Detection of throw-in-override, parameter type narrowing, return type widening
Interfaces that force implementors to depend on methods they don't use — detected by counting interface members and checking for partial implementations.
How it's measured
Interface member counting, stub method detection in implementations
Threshold
Interface with > 8 members or implementation with stub methods
High-level modules depending on low-level details — direct instantiation with new, importing concrete classes where abstractions belong.
How it's measured
Detection of direct instantiation across architectural layers, concrete import analysis
Complexity gates run during SOLID analysis but apply universally. Our definition is the standard cyclomatic measure: decision points + 1.
Decision Points Counted
Default Thresholds
Thresholds are configurable per architectural layer (utility functions tolerate higher complexity than controllers).
The hook fires on every agent edit. Only changed files are audited — a full-project audit takes seconds, a diff-scoped one is instant. Each analyzer produces structured violations with file, line, severity, rule ID, and a human-readable message the agent can act on.