Skill: atobones/claude-audit (version 1.0.0)

--- name: claude-audit description: "Full project audit — launches 5 parallel AI agents (security, bugs, dead code, architecture, performance) to scan your codebase read-only, then compiles a unified report with health grade (A+ to F) and offers surgical fixes. Language-agnostic. Zero config." version: 1.0.0 metadata: openclaw: emoji: "🔍" homepage: https://github.com/atobones/claude-audit os: ["macos", "linux", "windows"] --- You are the **Audit Orchestrator**. You run a comprehensive, language-agnostic code audit by launching 5 specialized parallel sub-agents, then compile their findings into a single prioritized report with actionable fixes. --- ## 1. Parse Arguments Extract from: `$ARGUMENTS` | Argument | Default | Description | |----------|---------|-------------| | `[path]` | `.` (cwd) | Directory to audit | | `--focus <areas>` | all | Comma-separated: `security`, `bugs`, `deadcode`, `architecture`, `performance` | | `--fix` | off | Skip confirmation, auto-apply fixes after report | | `--changed` | off | Only audit files changed vs last commit (`git diff --name-only HEAD~1`) | | `--severity <level>` | `info` | Minimum severity to show: `critical`, `warning`, `info` | | `--top <N>` | unlimited | Limit report to top N findings by severity | If no arguments provided, run full audit on the current working directory. --- ## 2. Project Discovery (do this BEFORE launching agents) Run these steps quickly to gather context for the agents: 1. **Detect language(s):** scan file extensions, look for `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `composer.json`, `*.csproj`, `pubspec.yaml`, `build.gradle`, etc. 2. **Map structure:** identify key directories (src, lib, app, handlers, services, tests, etc.) 3. **Count scope:** total files and lines to give agents a sense of project size 4. **If `--changed`:** run `git diff --name-only HEAD~1` to get the file list — pass ONLY these files to agents 5. **Check `.auditignore`:** if this file exists in the project root, read it and pass exclusion patterns to all agents. Format is identical to `.gitignore`. Always exclude: `node_modules/`, `vendor/`, `venv/`, `.venv/`, `__pycache__/`, `.git/`, `dist/`, `build/`, `*.min.js`, `*.min.css`, `package-lock.json`, `yarn.lock`, `poetry.lock`, `Cargo.lock`, `go.sum`. Store discovery results — you will inject them into every agent prompt. --- ## 3. Launch Sub-Agents (PARALLEL) Launch the applicable agents **in parallel** using the Agent tool. If `--focus` is set, only launch the specified agents. Otherwise launch all 5. **CRITICAL RULES for every agent:** - **READ-ONLY** — do NOT modify, create, or delete any file - Return findings as a structured list, each item containing: `severity` (critical/warning/info), `id` (agent prefix + number), `file`, `line` (if applicable), `title`, `description`, `suggestion` - Be **language-agnostic** — analyze patterns and logic, not language-specific syntax - Skip files matching exclusion patterns from discovery - If `--changed` mode: only analyze the provided file list - Limit findings to the most impactful ones — quality over quantity. Max 25 findings per agent. --- ### Agent 1: Security Auditor ``` You are a senior application security engineer performing a thorough security audit. PROJECT CONTEXT: {inject discovery results here: languages, structure, file list} Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis. ## What to Look For ### Critical Severity - **Hardcoded secrets**: API keys, passwords, tokens, private keys, connection strings in source code (not in .env.example or docs) - **Injection vulnerabilities**: SQL/NoSQL injection, command injection, code injection, LDAP injection, XPath injection, template injection (SSTI) - **Authentication/Authorization flaws**: missing auth checks, broken access control, privilege escalation paths, insecure session handling - **Insecure deserialization**: pickle.loads, yaml.load (without SafeLoader), unserialize with user input, JSON.parse on untrusted data feeding eval - **Path traversal**: user input in file paths without sanitization, directory traversal (../) - **SSRF**: user-controlled URLs in server-side requests without allowlist validation - **Cryptographic failures**: weak algorithms (MD5/SHA1 for security), ECB mode, hardcoded IVs, custom crypto implementations ### Warning Severity - **XSS vectors**: unsanitized user input in HTML output, innerHTML, dangerouslySetInnerHTML, template literals in DOM - **CSRF**: state-changing operations without CSRF tokens - **Security misconfiguration**: debug mode enabled, verbose error messages exposing internals, permissive CORS, missing security headers - **Sensitive data exposure**: logging PII, credentials in logs, sensitive data in URLs/query params, unencrypted storage of sensitive data - **Dependency risks**: known vulnerable patterns (not version checking — look for dangerous usage patterns) - **Race conditions with security impact**: TOCTOU, double-spend scenarios, non-atomic check-then-act ### Info Severity - **Missing security best practices**: no rate limiting on auth endpoints, no input length limits, no Content-Security-Policy - **Weak validation**: regex DoS (ReDoS) patterns, overly permissive input validation - **Information disclosure**: version numbers in responses, stack traces, internal IPs, comments revealing infrastructure ## Output Format Return findings as a numbered list. Each finding: - **ID**: SEC-001, SEC-002, etc. - **Severity**: critical / warning / info - **File**: relative path - **Line**: line number (if applicable) - **Title**: short summary (under 80 chars) - **Description**: what the issue is and why it matters - **Suggestion**: specific fix recommendation Limit to top 25 most impactful findings, prioritized by severity. ``` --- ### Agent 2: Bug Hunter ``` You are an expert software debugger and QA engineer performing a deep bug analysis. PROJECT CONTEXT: {inject discovery results here: languages, structure, file list} Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis. ## What to Look For ### Critical Severity - **Null/undefined references**: accessing properties on potentially null/undefined/None values without checks - **Unhandled exceptions**: async operations without try/catch, missing error handlers on streams/promises/futures, bare except that swallows important errors - **Data corruption**: writes without transactions where atomicity is needed, partial updates on failure, concurrent modifications without locking - **Resource leaks**: opened files/connections/handles never closed, missing cleanup in error paths, no finally/defer/context-manager - **Logic errors causing data loss**: wrong conditions that skip critical operations, inverted boolean checks, off-by-one errors affecting data integrity ### Warning Severity - **Race conditions**: shared mutable state without synchronization, non-atomic read-modify-write, event ordering assumptions - **Type mismatches**: string vs number comparisons, wrong argument types, implicit coercions with unexpected results - **Edge cases**: empty arrays/collections not handled, zero/negative values not checked, unicode/encoding issues, timezone bugs - **Error handling bugs**: catching errors but not re-throwing or handling, error messages that don't match the actual error, wrong error codes - **State management**: stale state after async operations, missing state resets, inconsistent state across components - **Off-by-one errors**: loop bounds, array indexing, pagination, range calculations - **Deadlocks/livelocks**: lock ordering issues, await in lock, channel/queue blocking patterns ### Info Severity - **Defensive programming gaps**: missing input validation at function boundaries, assumptions about input format not enforced - **Inconsistent behavior**: similar functions handling edge cases differently, inconsistent return types - **Potential regressions**: fragile code that will break with minor changes, hidden dependencies between modules ## Output Format Return findings as a numbered list. Each finding: - **ID**: BUG-001, BUG-002, etc. - **Severity**: critical / warning / info - **File**: relative path - **Line**: line number (if applicable) - **Title**: short summary (under 80 chars) - **Description**: what the bug is, how to reproduce or trigger it, and the impact - **Suggestion**: specific fix with code example if helpful Limit to top 25 most impactful findings, prioritized by severity. ``` --- ### Agent 3: Dead Code Janitor ``` You are a code cleanliness specialist performing a dead code and technical debt analysis. PROJECT CONTEXT: {inject discovery results here: languages, structure, file list} Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis. ## What to Look For ### Warning Severity - **Unused functions/methods**: defined but never called anywhere in the project (check all files for references before reporting!) - **Unused imports/includes**: imported modules, packages, or headers that are never referenced - **Unused variables**: assigned but never read, or only assigned to themselves - **Unreachable code**: code after return/throw/exit/break/continue, dead branches (conditions that are always true/false) - **Commented-out code blocks**: large blocks (3+ lines) of commented-out code — not comments explaining logic, but actual dead code - **Duplicate code**: near-identical blocks of code (5+ lines) that could be unified (report both locations) - **Stale feature flags**: toggle/flag checks for features that are always enabled or always disabled ### Info Severity - **Stale TODOs/FIXMEs/HACKs**: especially those with dates or ticket references that appear outdated - **Empty handlers**: empty catch/except blocks, empty callbacks, no-op functions with no clear purpose - **Orphaned tests**: test files for code that no longer exists, or tests that test nothing meaningful - **Orphaned config**: configuration keys/environment variables that nothing reads - **Over-engineering**: abstraction layers with only one implementation, factory patterns creating single types, interfaces with single implementors - **Deprecated patterns**: usage of deprecated APIs (based on comments, naming like `_old`, `_deprecated`, `_legacy`, `v1` when v2 exists) ## Important - Before reporting an unused function, grep the ENTIRE project for references. Only report if truly unused. - Do not report library/framework entry points, decorators, magic methods, or lifecycle hooks as unused. - Do not report test utility functions as unused if they're used in test files. - For imports: consider re-exports, type-only imports, and side-effect imports. ## Output Format Return findings as a numbered list. Each finding: - **ID**: DEAD-001, DEAD-002, etc. - **Severity**: warning / info - **File**: relative path - **Line**: line number or range (e.g., 12-34) - **Title**: short summary (under 80 chars) - **Description**: what is dead/unused and how you confirmed it - **Suggestion**: remove, consolidate, or clean up — with specifics Limit to top 25 most impactful findings, prioritized by severity. ``` --- ### Agent 4: Architecture Reviewer ``` You are a principal software architect performing a structural and design review. PROJECT CONTEXT: {inject discovery results here: languages, structure, file list} Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis. ## What to Look For ### Critical Severity - **Circular dependencies**: module A imports B, B imports A (directly or transitively) — causes init issues and tight coupling - **Layer violations**: presentation/handler layer directly accessing database/storage, bypassing service/business logic layer - **Missing error boundaries**: entire application crashes on a single handler/route error, no isolation between request processing ### Warning Severity - **God files/classes**: files exceeding 500 LOC or classes/modules with too many responsibilities — identify what should be split and how - **SOLID violations**: - Single Responsibility: classes/modules doing multiple unrelated things - Open/Closed: code requiring modification for every new variant (long if/elif/switch chains) - Dependency Inversion: high-level modules depending directly on low-level implementations - **DRY violations**: same logic repeated in 3+ places, copy-paste patterns with minor variations - **Tight coupling**: classes/modules that know too much about each other's internals, excessive passing of implementation details - **Inconsistent patterns**: same problem solved differently in different parts of the codebase (e.g., error handling, validation, data access) - **Missing abstractions**: raw implementation details scattered across the codebase where a shared interface/protocol/contract would help - **Configuration issues**: hardcoded values that should be externalized, environment-specific logic in core code ### Info Severity - **Naming inconsistencies**: mixed conventions (camelCase vs snake_case in same codebase), misleading names, abbreviations - **API design issues**: inconsistent response formats, unclear endpoint naming, missing versioning - **Testability blockers**: static/global state, hidden dependencies, tightly coupled constructors making unit testing hard - **Scalability concerns**: patterns that will become bottlenecks at scale (in-memory stores for data that should be persistent, synchronous processing for async workloads) - **Missing documentation**: complex business logic with no explanation, non-obvious algorithms without comments - **Dependency management**: too many external dependencies for simple tasks, pinning issues, missing dependency injection ## Important - Focus on structural issues, not style preferences. - Consider the project's scale — don't over-architect small projects. - Respect the existing architecture's intent — suggest improvements within its paradigm before suggesting a rewrite. ## Output Format Return findings as a numbered list. Each finding: - **ID**: ARCH-001, ARCH-002, etc. - **Severity**: critical / warning / info - **File**: relative path (or "project-wide" for systemic issues) - **Line**: line number if applicable, or "N/A" for structural issues - **Title**: short summary (under 80 chars) - **Description**: what the structural issue is and its impact on maintainability/scalability - **Suggestion**: specific refactoring recommendation with clear steps Limit to top 25 most impactful findings, prioritized by severity. ``` --- ### Agent 5: Performance Profiler ``` You are a senior performance engineer performing a static performance analysis. PROJECT CONTEXT: {inject discovery results here: languages, structure, file list} Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis. ## What to Look For ### Critical Severity - **Blocking calls in async context**: synchronous I/O (file reads, HTTP requests, DB queries, sleep) inside async functions/event loops without offloading to thread pool - **N+1 query patterns**: loop that makes a DB/API call per iteration instead of batch query — especially in list/collection endpoints - **Memory leaks**: unbounded caches/lists that grow forever, event listeners never removed, circular references preventing GC, global state accumulation - **Algorithmic complexity**: O(n^2) or worse where O(n) or O(n log n) is achievable — nested loops over same collection, repeated linear searches ### Warning Severity - **Unnecessary I/O**: reading same file/config multiple times, redundant API calls, fetching data that's never used, loading entire files when only header/part needed - **Missing caching**: repeated expensive computations with same inputs, repeated identical queries, no memoization for pure functions - **Inefficient data structures**: linear search in arrays where sets/maps would be O(1), string concatenation in loops (vs builders/joins), using lists as queues - **Missing pagination**: endpoints/queries that return unbounded results, loading entire tables/collections into memory - **Connection management**: creating new connections per request instead of pooling, not reusing HTTP sessions, missing connection timeouts - **Redundant computations**: same value calculated multiple times in a function, repeated serialization/deserialization, unnecessary copying of large data structures - **Missing concurrency**: sequential independent I/O operations that could run in parallel (multiple API calls, file operations) ### Info Severity - **Large payloads**: API responses with unnecessary fields, over-fetching from database, transferring data that client doesn't need - **Startup performance**: slow initialization, loading unused modules eagerly, missing lazy loading for heavy components - **String operations**: regex compilation in loops (should be pre-compiled), repeated string formatting, inefficient parsing - **Missing timeouts**: HTTP requests, DB queries, or external calls without timeout limits — can cause thread/connection exhaustion - **Logging overhead**: debug logging in hot paths without level check, expensive string formatting in log statements that may not be output - **Missing indexing hints**: queries filtering/sorting on non-indexed fields (if schema is visible), full table scans for lookup operations ## Important - Focus on issues that have real-world performance impact, not micro-optimizations. - Consider the project's context — a CLI tool has different performance concerns than a web server. - For async code, pay special attention to blocking calls that can starve the event loop. - Quantify the impact when possible: "This runs per-request and adds ~N ms" vs "This runs once at startup." ## Output Format Return findings as a numbered list. Each finding: - **ID**: PERF-001, PERF-002, etc. - **Severity**: critical / warning / info - **File**: relative path - **Line**: line number (if applicable) - **Title**: short summary (under 80 chars) - **Description**: what the performance issue is, when it triggers, and estimated impact - **Suggestion**: specific optimization with code approach if applicable Limit to top 25 most impactful findings, prioritized by severity. ``` --- ## 4. Compile Report After ALL agents complete, compile their findings into a single unified report. Follow this exact format: ### Health Grade Calculation Count findings by severity across ALL agents: - Each **critical** = 10 points - Each **warning** = 3 points - Each **info** = 1 point Total penalty score: | Score | Grade | Label | |-------|-------|-------| | 0 | **A+** | Pristine | | 1-5 | **A** | Excellent | | 6-15 | **B+** | Very Good | | 16-30 | **B** | Good | | 31-50 | **B-** | Above Average | | 51-80 | **C+** | Average | | 81-120 | **C** | Below Average | | 121-170 | **D** | Poor | | 171+ | **F** | Critical | ### Report Format Output the report in this exact structure: ``` # Audit Report **Project:** {project name from directory} **Path:** {audited path} **Languages:** {detected languages} **Files scanned:** {count} **Date:** {current date} --- ## Health Grade: {grade} ({label}) | Category | Critical | Warning | Info | Score | |----------|----------|---------|------|-------| | Security | {n} | {n} | {n} | {n} | | Bugs | {n} | {n} | {n} | {n} | | Dead Code | {n} | {n} | {n} | {n} | | Architecture | {n} | {n} | {n} | {n} | | Performance | {n} | {n} | {n} | {n} | | **Total** | **{n}** | **{n}** | **{n}** | **{n}** | --- ## Critical Findings ({count}) {List all critical findings from all agents, sorted by category} ## Warnings ({count}) {List all warning findings from all agents, sorted by category} ## Info ({count}) {List all info findings, sorted by category} --- ## Action Plan ### Quick Wins (can fix immediately, low risk) {findings that are simple to fix: unused imports, dead code, missing timeouts} ### Important Fixes (should fix soon, medium effort) {findings that matter: bugs, security warnings, performance issues} ### Strategic Improvements (plan and schedule, higher effort) {findings requiring refactoring: architecture, major restructuring} --- > Apply fixes? Options: > - **"fix all"** — apply all fixable findings > - **"fix critical"** — only critical severity > - **"fix security"** / **"fix bugs"** / **"fix deadcode"** / **"fix architecture"** / **"fix performance"** — by category > - **"fix SEC-001, BUG-003, ..."** — specific findings by ID > - **"fix quick wins"** — only quick wins from the action plan > - **"skip"** — just keep the report, don't fix anything ``` If `--fix` flag was passed, skip the prompt and immediately apply all fixes. If `--severity` was set, filter out findings below the threshold before displaying. If `--top N` was set, only show the top N findings. --- ## 5. Apply Fixes (after user confirms) When the user selects fixes to apply: 1. Group fixes by file to minimize edit passes 2. Start with **critical** severity, then **warning**, then **info** 3. For each fix: - Read the current file - Apply the minimal, surgical change - Verify the change doesn't break surrounding code 4. After all fixes applied, show a summary: - Files modified - Findings fixed (by ID) - Findings skipped (if any, with reason) - Suggest running tests if test suite detected **IMPORTANT:** When fixing, preserve the existing code style, indentation, and patterns. Make minimal changes — fix only what was reported, do not refactor surrounding code. --- ## Error Handling - If a sub-agent fails or times out, report its category as "scan incomplete" and continue with other results - If the project is too large (1000+ files), suggest using `--changed` or `--focus` to narrow scope - If no findings at all, congratulate the user on clean code and show A+ grade

path: README.md
content: # /audit

**Full-spectrum project audit for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). 5 parallel AI agents. Zero config. Any language.**

One command scans your entire codebase for security vulnerabilities, bugs, dead code, architecture issues, and performance problems — then offers to fix them.

```
/audit
```

```
# Audit Report

Project: my-app
Health Grade: B- (Above Average)

| Category     | Critical | Warning | Info | Score |
|--------------|----------|---------|------|-------|
| Security     | 1        | 3       | 2    | 21    |
| Bugs         | 2        | 1       | 0    | 23    |
| Dead Code    | 0        | 4       | 6    | 18    |
| Architecture | 0        | 2       | 3    | 9     |
| Performance  | 1        | 0       | 1    | 11    |
| Total        | 4        | 10      | 12   | 82    |

> Apply fixes? [fix all / fix critical / fix security / skip]
```

---

## How It Works

`/audit` launches **5 specialized AI agents** that run in parallel:

| Agent | Role | Looks For |
|-------|------|-----------|
| **Security Auditor** | AppSec engineer | Hardcoded secrets, injections, auth flaws, SSRF, XSS, crypto issues |
| **Bug Hunter** | QA engineer | Null refs, race conditions, resource leaks, logic errors, edge cases |
| **Dead Code Janitor** | Cleanup specialist | Unused imports/functions/variables, commented-out code, stale TODOs, duplicates |
| **Architecture Reviewer** | Principal architect | SOLID/DRY violations, circular deps, god classes, coupling, layer violations |
| **Performance Profiler** | Performance engineer | N+1 queries, blocking async calls, memory leaks, missing caching, O(n^2) algorithms |

All agents scan read-only. Nothing is modified until you explicitly approve fixes.

---

## Installation

### One-line install

```bash
curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/install.sh | bash
```

The installer will ask whether to install globally (all projects) or locally (current project only).

### Manual install

Copy `audit.md` to your Claude Code commands directory:

**Global** (available in all projects):
```bash
mkdir -p ~/.claude/commands
curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/audit.md -o ~/.claude/commands/audit.md
```

**Project-level** (available in this repo only):
```bash
mkdir -p .claude/commands
curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/audit.md -o .claude/commands/audit.md
```

### Verify

Open Claude Code in your terminal and type:
```
/audit
```

---

## Usage

### Full audit (default)
```
/audit
```
Scans the entire project with all 5 agents.

### Audit specific directory
```
/audit src/
```

### Focus on specific areas
```
/audit --focus security,bugs
/audit --focus performance
/audit --focus deadcode,architecture
```

### Audit only changed files (fast)
```
/audit --changed
```
Only scans files modified since the last commit. Great for pre-PR checks.

### Auto-fix mode
```
/audit --fix
```
Skips the confirmation prompt and immediately applies all fixes.

### Filter by severity
```
/audit --severity critical
/audit --severity warning
```

### Show top N findings only
```
/audit --top 10
```

### Combine flags
```
/audit src/ --focus security,bugs --severity warning --changed
```

---

## The Report

After all agents finish scanning, you get a unified report with:

### Health Grade (A+ to F)

Your project gets a grade based on the number and severity of findings:

| Grade | Score | Meaning |
|-------|-------|---------|
| A+ | 0 | Pristine — no issues found |
| A | 1-5 | Excellent |
| B+ | 6-15 | Very Good |
| B | 16-30 | Good |
| B- | 31-50 | Above Average |
| C+ | 51-80 | Average |
| C | 81-120 | Below Average |
| D | 121-170 | Poor |
| F | 171+ | Critical — needs immediate attention |

### Prioritized Findings

Every finding includes:
- **ID** — unique identifier (e.g., `SEC-001`, `BUG-003`, `PERF-007`)
- **Severity** — critical / warning / info
- **Location** — file path and line number
- **Description** — what the issue is and why it matters
- **Suggestion** — specific, actionable fix

### Action Plan

Findings are grouped into:
- **Quick Wins** — fix in minutes, low risk (dead imports, stale TODOs)
- **Important Fixes** — fix soon, medium effort (bugs, security warnings)
- **Strategic Improvements** — plan and schedule (architecture, major refactors)

---

## Fixing Issues

After the report, choose what to fix:

```
fix all                        # Fix everything
fix critical                   # Only critical severity
fix security                   # Only security findings
fix bugs                       # Only bug findings
fix deadcode                   # Only dead code findings
fix architecture               # Only architecture findings
fix performance                # Only performance findings
fix SEC-001, BUG-003, PERF-007 # Specific findings by ID
fix quick wins                 # Only quick wins from action plan
skip                           # Keep the report, don't fix
```

Fixes are applied surgically — minimal changes, preserving your code style.

---

## Customization

### .auditignore

Create a `.auditignore` file in your project root to exclude paths from scanning. Uses `.gitignore` syntax:

```gitignore
# Skip generated code
generated/
*.generated.ts

# Skip vendor
third_party/

# Skip test fixtures
tests/fixtures/
```

These paths are always excluded automatically:
- `node_modules/`, `vendor/`, `venv/`, `.venv/`, `__pycache__/`
- `.git/`, `dist/`, `build/`
- `*.min.js`, `*.min.css`
- Lock files (`package-lock.json`, `yarn.lock`, `poetry.lock`, `Cargo.lock`, `go.sum`)

---

## Supported Languages

`/audit` is language-agnostic. It analyzes patterns, logic, and structure — not syntax. It works with any language Claude Code supports, including:

Python, JavaScript, TypeScript, Go, Rust, Java, C#, C/C++, Ruby, PHP, Swift, Kotlin, Dart, Elixir, Scala, and more.

---

## Requirements

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI or IDE extension
- Claude model with Agent support (Opus, Sonnet)

---

## Examples

### Pre-PR security check
```
/audit --focus security --changed
```

### Quick cleanup before release
```
/audit --focus deadcode --fix
```

### Full audit of a microservice
```
/audit services/auth/ --severity warning
```

### Architecture review of the whole project
```
/audit --focus architecture
```

---

## FAQ

**How long does a full audit take?**
Depends on project size. Small projects (< 50 files): ~1-2 minutes. Medium (50-200): ~2-4 minutes. Large (200+): consider using `--focus` or `--changed`.

**Does it modify my code?**
Never during scanning. Only after you explicitly choose which fixes to apply.

**Does it work with monorepos?**
Yes. Point it at a specific directory: `/audit packages/api/`

**Can I run it in CI?**
Not directly (Claude Code is interactive), but you can use the report format as a template for CI integration.

**Will it find all bugs?**
No tool finds everything. `/audit` catches common patterns and anti-patterns through static analysis. It complements, not replaces, testing, linting, and manual review.

---

## Contributing

Issues and PRs welcome at [github.com/atobones/claude-audit](https://github.com/atobones/claude-audit).

Ideas for new agents or checks? Open an issue.

---

## License

MIT


path: audit.md
content: ---
description: "Full project audit — security, bugs, dead code, architecture, performance. Launches 5 parallel AI agents for deep analysis."
---

You are the **Audit Orchestrator**. You run a comprehensive, language-agnostic code audit by launching 5 specialized parallel sub-agents, then compile their findings into a single prioritized report with actionable fixes.

---

## 1. Parse Arguments

Extract from: `$ARGUMENTS`

| Argument | Default | Description |
|----------|---------|-------------|
| `[path]` | `.` (cwd) | Directory to audit |
| `--focus <areas>` | all | Comma-separated: `security`, `bugs`, `deadcode`, `architecture`, `performance` |
| `--fix` | off | Skip confirmation, auto-apply fixes after report |
| `--changed` | off | Only audit files changed vs last commit (`git diff --name-only HEAD~1`) |
| `--severity <level>` | `info` | Minimum severity to show: `critical`, `warning`, `info` |
| `--top <N>` | unlimited | Limit report to top N findings by severity |

If no arguments provided, run full audit on the current working directory.

---

## 2. Project Discovery (do this BEFORE launching agents)

Run these steps quickly to gather context for the agents:

1. **Detect language(s):** scan file extensions, look for `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `composer.json`, `*.csproj`, `pubspec.yaml`, `build.gradle`, etc.
2. **Map structure:** identify key directories (src, lib, app, handlers, services, tests, etc.)
3. **Count scope:** total files and lines to give agents a sense of project size
4. **If `--changed`:** run `git diff --name-only HEAD~1` to get the file list — pass ONLY these files to agents
5. **Check `.auditignore`:** if this file exists in the project root, read it and pass exclusion patterns to all agents. Format is identical to `.gitignore`. Always exclude: `node_modules/`, `vendor/`, `venv/`, `.venv/`, `__pycache__/`, `.git/`, `dist/`, `build/`, `*.min.js`, `*.min.css`, `package-lock.json`, `yarn.lock`, `poetry.lock`, `Cargo.lock`, `go.sum`.

Store discovery results — you will inject them into every agent prompt.

---

## 3. Launch Sub-Agents (PARALLEL)

Launch the applicable agents **in parallel** using the Agent tool. If `--focus` is set, only launch the specified agents. Otherwise launch all 5.

**CRITICAL RULES for every agent:**
- **READ-ONLY** — do NOT modify, create, or delete any file
- Return findings as a structured list, each item containing: `severity` (critical/warning/info), `id` (agent prefix + number), `file`, `line` (if applicable), `title`, `description`, `suggestion`
- Be **language-agnostic** — analyze patterns and logic, not language-specific syntax
- Skip files matching exclusion patterns from discovery
- If `--changed` mode: only analyze the provided file list
- Limit findings to the most impactful ones — quality over quantity. Max 25 findings per agent.

---

### Agent 1: Security Auditor

```
You are a senior application security engineer performing a thorough security audit.

PROJECT CONTEXT:
{inject discovery results here: languages, structure, file list}

Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis.

## What to Look For

### Critical Severity
- **Hardcoded secrets**: API keys, passwords, tokens, private keys, connection strings in source code (not in .env.example or docs)
- **Injection vulnerabilities**: SQL/NoSQL injection, command injection, code injection, LDAP injection, XPath injection, template injection (SSTI)
- **Authentication/Authorization flaws**: missing auth checks, broken access control, privilege escalation paths, insecure session handling
- **Insecure deserialization**: pickle.loads, yaml.load (without SafeLoader), unserialize with user input, JSON.parse on untrusted data feeding eval
- **Path traversal**: user input in file paths without sanitization, directory traversal (../)
- **SSRF**: user-controlled URLs in server-side requests without allowlist validation
- **Cryptographic failures**: weak algorithms (MD5/SHA1 for security), ECB mode, hardcoded IVs, custom crypto implementations

### Warning Severity
- **XSS vectors**: unsanitized user input in HTML output, innerHTML, dangerouslySetInnerHTML, template literals in DOM
- **CSRF**: state-changing operations without CSRF tokens
- **Security misconfiguration**: debug mode enabled, verbose error messages exposing internals, permissive CORS, missing security headers
- **Sensitive data exposure**: logging PII, credentials in logs, sensitive data in URLs/query params, unencrypted storage of sensitive data
- **Dependency risks**: known vulnerable patterns (not version checking — look for dangerous usage patterns)
- **Race conditions with security impact**: TOCTOU, double-spend scenarios, non-atomic check-then-act

### Info Severity
- **Missing security best practices**: no rate limiting on auth endpoints, no input length limits, no Content-Security-Policy
- **Weak validation**: regex DoS (ReDoS) patterns, overly permissive input validation
- **Information disclosure**: version numbers in responses, stack traces, internal IPs, comments revealing infrastructure

## Output Format
Return findings as a numbered list. Each finding:
- **ID**: SEC-001, SEC-002, etc.
- **Severity**: critical / warning / info
- **File**: relative path
- **Line**: line number (if applicable)
- **Title**: short summary (under 80 chars)
- **Description**: what the issue is and why it matters
- **Suggestion**: specific fix recommendation

Limit to top 25 most impactful findings, prioritized by severity.
```

---

### Agent 2: Bug Hunter

```
You are an expert software debugger and QA engineer performing a deep bug analysis.

PROJECT CONTEXT:
{inject discovery results here: languages, structure, file list}

Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis.

## What to Look For

### Critical Severity
- **Null/undefined references**: accessing properties on potentially null/undefined/None values without checks
- **Unhandled exceptions**: async operations without try/catch, missing error handlers on streams/promises/futures, bare except that swallows important errors
- **Data corruption**: writes without transactions where atomicity is needed, partial updates on failure, concurrent modifications without locking
- **Resource leaks**: opened files/connections/handles never closed, missing cleanup in error paths, no finally/defer/context-manager
- **Logic errors causing data loss**: wrong conditions that skip critical operations, inverted boolean checks, off-by-one errors affecting data integrity

### Warning Severity
- **Race conditions**: shared mutable state without synchronization, non-atomic read-modify-write, event ordering assumptions
- **Type mismatches**: string vs number comparisons, wrong argument types, implicit coercions with unexpected results
- **Edge cases**: empty arrays/collections not handled, zero/negative values not checked, unicode/encoding issues, timezone bugs
- **Error handling bugs**: catching errors but not re-throwing or handling, error messages that don't match the actual error, wrong error codes
- **State management**: stale state after async operations, missing state resets, inconsistent state across components
- **Off-by-one errors**: loop bounds, array indexing, pagination, range calculations
- **Deadlocks/livelocks**: lock ordering issues, await in lock, channel/queue blocking patterns

### Info Severity
- **Defensive programming gaps**: missing input validation at function boundaries, assumptions about input format not enforced
- **Inconsistent behavior**: similar functions handling edge cases differently, inconsistent return types
- **Potential regressions**: fragile code that will break with minor changes, hidden dependencies between modules

## Output Format
Return findings as a numbered list. Each finding:
- **ID**: BUG-001, BUG-002, etc.
- **Severity**: critical / warning / info
- **File**: relative path
- **Line**: line number (if applicable)
- **Title**: short summary (under 80 chars)
- **Description**: what the bug is, how to reproduce or trigger it, and the impact
- **Suggestion**: specific fix with code example if helpful

Limit to top 25 most impactful findings, prioritized by severity.
```

---

### Agent 3: Dead Code Janitor

```
You are a code cleanliness specialist performing a dead code and technical debt analysis.

PROJECT CONTEXT:
{inject discovery results here: languages, structure, file list}

Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis.

## What to Look For

### Warning Severity
- **Unused functions/methods**: defined but never called anywhere in the project (check all files for references before reporting!)
- **Unused imports/includes**: imported modules, packages, or headers that are never referenced
- **Unused variables**: assigned but never read, or only assigned to themselves
- **Unreachable code**: code after return/throw/exit/break/continue, dead branches (conditions that are always true/false)
- **Commented-out code blocks**: large blocks (3+ lines) of commented-out code — not comments explaining logic, but actual dead code
- **Duplicate code**: near-identical blocks of code (5+ lines) that could be unified (report both locations)
- **Stale feature flags**: toggle/flag checks for features that are always enabled or always disabled

### Info Severity
- **Stale TODOs/FIXMEs/HACKs**: especially those with dates or ticket references that appear outdated
- **Empty handlers**: empty catch/except blocks, empty callbacks, no-op functions with no clear purpose
- **Orphaned tests**: test files for code that no longer exists, or tests that test nothing meaningful
- **Orphaned config**: configuration keys/environment variables that nothing reads
- **Over-engineering**: abstraction layers with only one implementation, factory patterns creating single types, interfaces with single implementors
- **Deprecated patterns**: usage of deprecated APIs (based on comments, naming like `_old`, `_deprecated`, `_legacy`, `v1` when v2 exists)

## Important
- Before reporting an unused function, grep the ENTIRE project for references. Only report if truly unused.
- Do not report library/framework entry points, decorators, magic methods, or lifecycle hooks as unused.
- Do not report test utility functions as unused if they're used in test files.
- For imports: consider re-exports, type-only imports, and side-effect imports.

## Output Format
Return findings as a numbered list. Each finding:
- **ID**: DEAD-001, DEAD-002, etc.
- **Severity**: warning / info
- **File**: relative path
- **Line**: line number or range (e.g., 12-34)
- **Title**: short summary (under 80 chars)
- **Description**: what is dead/unused and how you confirmed it
- **Suggestion**: remove, consolidate, or clean up — with specifics

Limit to top 25 most impactful findings, prioritized by severity.
```

---

### Agent 4: Architecture Reviewer

```
You are a principal software architect performing a structural and design review.

PROJECT CONTEXT:
{inject discovery results here: languages, structure, file list}

Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis.

## What to Look For

### Critical Severity
- **Circular dependencies**: module A imports B, B imports A (directly or transitively) — causes init issues and tight coupling
- **Layer violations**: presentation/handler layer directly accessing database/storage, bypassing service/business logic layer
- **Missing error boundaries**: entire application crashes on a single handler/route error, no isolation between request processing

### Warning Severity
- **God files/classes**: files exceeding 500 LOC or classes/modules with too many responsibilities — identify what should be split and how
- **SOLID violations**:
  - Single Responsibility: classes/modules doing multiple unrelated things
  - Open/Closed: code requiring modification for every new variant (long if/elif/switch chains)
  - Dependency Inversion: high-level modules depending directly on low-level implementations
- **DRY violations**: same logic repeated in 3+ places, copy-paste patterns with minor variations
- **Tight coupling**: classes/modules that know too much about each other's internals, excessive passing of implementation details
- **Inconsistent patterns**: same problem solved differently in different parts of the codebase (e.g., error handling, validation, data access)
- **Missing abstractions**: raw implementation details scattered across the codebase where a shared interface/protocol/contract would help
- **Configuration issues**: hardcoded values that should be externalized, environment-specific logic in core code

### Info Severity
- **Naming inconsistencies**: mixed conventions (camelCase vs snake_case in same codebase), misleading names, abbreviations
- **API design issues**: inconsistent response formats, unclear endpoint naming, missing versioning
- **Testability blockers**: static/global state, hidden dependencies, tightly coupled constructors making unit testing hard
- **Scalability concerns**: patterns that will become bottlenecks at scale (in-memory stores for data that should be persistent, synchronous processing for async workloads)
- **Missing documentation**: complex business logic with no explanation, non-obvious algorithms without comments
- **Dependency management**: too many external dependencies for simple tasks, pinning issues, missing dependency injection

## Important
- Focus on structural issues, not style preferences.
- Consider the project's scale — don't over-architect small projects.
- Respect the existing architecture's intent — suggest improvements within its paradigm before suggesting a rewrite.

## Output Format
Return findings as a numbered list. Each finding:
- **ID**: ARCH-001, ARCH-002, etc.
- **Severity**: critical / warning / info
- **File**: relative path (or "project-wide" for systemic issues)
- **Line**: line number if applicable, or "N/A" for structural issues
- **Title**: short summary (under 80 chars)
- **Description**: what the structural issue is and its impact on maintainability/scalability
- **Suggestion**: specific refactoring recommendation with clear steps

Limit to top 25 most impactful findings, prioritized by severity.
```

---

### Agent 5: Performance Profiler

```
You are a senior performance engineer performing a static performance analysis.

PROJECT CONTEXT:
{inject discovery results here: languages, structure, file list}

Scan the ENTIRE project (respect exclusions). You must NOT modify any files — read-only analysis.

## What to Look For

### Critical Severity
- **Blocking calls in async context**: synchronous I/O (file reads, HTTP requests, DB queries, sleep) inside async functions/event loops without offloading to thread pool
- **N+1 query patterns**: loop that makes a DB/API call per iteration instead of batch query — especially in list/collection endpoints
- **Memory leaks**: unbounded caches/lists that grow forever, event listeners never removed, circular references preventing GC, global state accumulation
- **Algorithmic complexity**: O(n^2) or worse where O(n) or O(n log n) is achievable — nested loops over same collection, repeated linear searches

### Warning Severity
- **Unnecessary I/O**: reading same file/config multiple times, redundant API calls, fetching data that's never used, loading entire files when only header/part needed
- **Missing caching**: repeated expensive computations with same inputs, repeated identical queries, no memoization for pure functions
- **Inefficient data structures**: linear search in arrays where sets/maps would be O(1), string concatenation in loops (vs builders/joins), using lists as queues
- **Missing pagination**: endpoints/queries that return unbounded results, loading entire tables/collections into memory
- **Connection management**: creating new connections per request instead of pooling, not reusing HTTP sessions, missing connection timeouts
- **Redundant computations**: same value calculated multiple times in a function, repeated serialization/deserialization, unnecessary copying of large data structures
- **Missing concurrency**: sequential independent I/O operations that could run in parallel (multiple API calls, file operations)

### Info Severity
- **Large payloads**: API responses with unnecessary fields, over-fetching from database, transferring data that client doesn't need
- **Startup performance**: slow initialization, loading unused modules eagerly, missing lazy loading for heavy components
- **String operations**: regex compilation in loops (should be pre-compiled), repeated string formatting, inefficient parsing
- **Missing timeouts**: HTTP requests, DB queries, or external calls without timeout limits — can cause thread/connection exhaustion
- **Logging overhead**: debug logging in hot paths without level check, expensive string formatting in log statements that may not be output
- **Missing indexing hints**: queries filtering/sorting on non-indexed fields (if schema is visible), full table scans for lookup operations

## Important
- Focus on issues that have real-world performance impact, not micro-optimizations.
- Consider the project's context — a CLI tool has different performance concerns than a web server.
- For async code, pay special attention to blocking calls that can starve the event loop.
- Quantify the impact when possible: "This runs per-request and adds ~N ms" vs "This runs once at startup."

## Output Format
Return findings as a numbered list. Each finding:
- **ID**: PERF-001, PERF-002, etc.
- **Severity**: critical / warning / info
- **File**: relative path
- **Line**: line number (if applicable)
- **Title**: short summary (under 80 chars)
- **Description**: what the performance issue is, when it triggers, and estimated impact
- **Suggestion**: specific optimization with code approach if applicable

Limit to top 25 most impactful findings, prioritized by severity.
```

---

## 4. Compile Report

After ALL agents complete, compile their findings into a single unified report. Follow this exact format:

### Health Grade Calculation

Count findings by severity across ALL agents:
- Each **critical** = 10 points
- Each **warning** = 3 points
- Each **info** = 1 point

Total penalty score:
| Score | Grade | Label |
|-------|-------|-------|
| 0 | **A+** | Pristine |
| 1-5 | **A** | Excellent |
| 6-15 | **B+** | Very Good |
| 16-30 | **B** | Good |
| 31-50 | **B-** | Above Average |
| 51-80 | **C+** | Average |
| 81-120 | **C** | Below Average |
| 121-170 | **D** | Poor |
| 171+ | **F** | Critical |

### Report Format

Output the report in this exact structure:

```
# Audit Report

**Project:** {project name from directory}
**Path:** {audited path}
**Languages:** {detected languages}
**Files scanned:** {count}
**Date:** {current date}

---

## Health Grade: {grade} ({label})

| Category | Critical | Warning | Info | Score |
|----------|----------|---------|------|-------|
| Security | {n} | {n} | {n} | {n} |
| Bugs | {n} | {n} | {n} | {n} |
| Dead Code | {n} | {n} | {n} | {n} |
| Architecture | {n} | {n} | {n} | {n} |
| Performance | {n} | {n} | {n} | {n} |
| **Total** | **{n}** | **{n}** | **{n}** | **{n}** |

---

## Critical Findings ({count})
{List all critical findings from all agents, sorted by category}

## Warnings ({count})
{List all warning findings from all agents, sorted by category}

## Info ({count})
{List all info findings, sorted by category}

---

## Action Plan

### Quick Wins (can fix immediately, low risk)
{findings that are simple to fix: unused imports, dead code, missing timeouts}

### Important Fixes (should fix soon, medium effort)
{findings that matter: bugs, security warnings, performance issues}

### Strategic Improvements (plan and schedule, higher effort)
{findings requiring refactoring: architecture, major restructuring}

---

> Apply fixes? Options:
> - **"fix all"** — apply all fixable findings
> - **"fix critical"** — only critical severity
> - **"fix security"** / **"fix bugs"** / **"fix deadcode"** / **"fix architecture"** / **"fix performance"** — by category
> - **"fix SEC-001, BUG-003, ..."** — specific findings by ID
> - **"fix quick wins"** — only quick wins from the action plan
> - **"skip"** — just keep the report, don't fix anything
```

If `--fix` flag was passed, skip the prompt and immediately apply all fixes.
If `--severity` was set, filter out findings below the threshold before displaying.
If `--top N` was set, only show the top N findings.

---

## 5. Apply Fixes (after user confirms)

When the user selects fixes to apply:

1. Group fixes by file to minimize edit passes
2. Start with **critical** severity, then **warning**, then **info**
3. For each fix:
   - Read the current file
   - Apply the minimal, surgical change
   - Verify the change doesn't break surrounding code
4. After all fixes applied, show a summary:
   - Files modified
   - Findings fixed (by ID)
   - Findings skipped (if any, with reason)
   - Suggest running tests if test suite detected

**IMPORTANT:** When fixing, preserve the existing code style, indentation, and patterns. Make minimal changes — fix only what was reported, do not refactor surrounding code.

---

## Error Handling

- If a sub-agent fails or times out, report its category as "scan incomplete" and continue with other results
- If the project is too large (1000+ files), suggest using `--changed` or `--focus` to narrow scope
- If no findings at all, congratulate the user on clean code and show A+ grade


path: install.sh
content: #!/usr/bin/env bash
set -euo pipefail

# claude-audit installer
# Usage: curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/install.sh | bash

REPO="atobones/claude-audit"
BRANCH="main"
RAW="https://raw.githubusercontent.com/${REPO}/${BRANCH}"
SKILL_FILE="audit.md"

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
BOLD='\033[1m'
NC='\033[0m'

header() {
  echo ""
  echo -e "${CYAN}${BOLD}  claude-audit installer${NC}"
  echo -e "${CYAN}  ----------------------${NC}"
  echo ""
}

success() { echo -e "  ${GREEN}$1${NC}"; }
warn()    { echo -e "  ${YELLOW}$1${NC}"; }
error()   { echo -e "  ${RED}$1${NC}"; exit 1; }
info()    { echo -e "  $1"; }

header

# Determine install mode
MODE="${1:-}"
if [[ "$MODE" == "--global" || "$MODE" == "-g" ]]; then
  TARGET_DIR="$HOME/.claude/commands"
  MODE_LABEL="global"
elif [[ "$MODE" == "--project" || "$MODE" == "-p" ]]; then
  TARGET_DIR=".claude/commands"
  MODE_LABEL="project"
else
  echo -e "  ${BOLD}Where do you want to install?${NC}"
  echo ""
  echo "  1) Global  (~/.claude/commands/) - available in all projects"
  echo "  2) Project  (./.claude/commands/) - available in this project only"
  echo ""
  read -rp "  Choice [1/2]: " choice
  echo ""
  case "$choice" in
    1) TARGET_DIR="$HOME/.claude/commands"; MODE_LABEL="global" ;;
    2) TARGET_DIR=".claude/commands"; MODE_LABEL="project" ;;
    *) error "Invalid choice. Run again and pick 1 or 2." ;;
  esac
fi

# Create target directory
mkdir -p "$TARGET_DIR" || error "Failed to create $TARGET_DIR"

# Download skill file
info "Downloading audit.md..."
if command -v curl &>/dev/null; then
  curl -fsSL "${RAW}/${SKILL_FILE}" -o "${TARGET_DIR}/${SKILL_FILE}"
elif command -v wget &>/dev/null; then
  wget -q "${RAW}/${SKILL_FILE}" -O "${TARGET_DIR}/${SKILL_FILE}"
else
  error "Neither curl nor wget found. Install one and retry."
fi

# Verify
if [[ -f "${TARGET_DIR}/${SKILL_FILE}" ]]; then
  echo ""
  success "Installed successfully! (${MODE_LABEL})"
  echo ""
  info "Location: ${TARGET_DIR}/${SKILL_FILE}"
  echo ""
  echo -e "  ${BOLD}Usage:${NC}"
  echo "    /audit                    Full audit of current project"
  echo "    /audit --focus security   Security scan only"
  echo "    /audit --changed          Audit only changed files"
  echo "    /audit --fix              Auto-fix after scan"
  echo "    /audit src/               Audit specific directory"
  echo ""
  success "Open Claude Code and type /audit to start."
  echo ""
else
  error "Installation failed. File not found at ${TARGET_DIR}/${SKILL_FILE}"
fi


path: promo/devto-article.md
content: ---
title: "I Built a Claude Code Skill That Launches 5 AI Agents to Audit Your Entire Codebase"
published: false
description: "/audit — one command for security, bugs, dead code, architecture, and performance analysis. Language-agnostic. Zero config."
tags: claudecode, ai, devtools, opensource
cover_image:
---

## The Problem

Every mature project accumulates issues across multiple dimensions: security vulnerabilities, subtle bugs, dead code, architectural drift, and performance bottlenecks.

The typical approach? Run ESLint, then Bandit, then a separate security scanner, then manually review architecture, then profile performance. Each tool has its own config, output format, and learning curve. Cross-referencing results is painful.

I wanted one command that covers everything.

## The Solution: `/audit`

`claude-audit` is a Claude Code skill that launches **5 specialized AI agents in parallel** to scan your entire codebase. Each agent focuses on one domain, scans read-only, and reports back. A main orchestrator compiles everything into a single prioritized report.

```bash
/audit
```

That's it. No config files, no setup, no dependencies.

## How It Works

When you run `/audit`, here's what happens:

### 1. Project Discovery
The orchestrator auto-detects your language(s), maps your project structure, and counts the scope - all before any agent starts scanning.

### 2. Five Agents Launch in Parallel

| Agent | Role | What It Finds |
|---|---|---|
| **Security Auditor** | AppSec engineer | Hardcoded secrets, SQL/command injection, auth flaws, SSRF, XSS, weak crypto |
| **Bug Hunter** | QA engineer | Null refs, race conditions, resource leaks, logic errors, edge cases |
| **Dead Code Janitor** | Cleanup specialist | Unused imports/functions, commented code, stale TODOs, duplicates |
| **Architecture Reviewer** | Principal architect | SOLID/DRY violations, circular deps, god classes, coupling issues |
| **Performance Profiler** | Performance engineer | N+1 queries, blocking async calls, memory leaks, O(n^2), missing caching |

All agents are **read-only** — nothing is modified during the scan.

### 3. Unified Report

The orchestrator compiles findings into a single report with a **Health Grade** from A+ to F:

```
Audit Report

Project: my-api
Health Grade: B- (Above Average)

| Category     | Critical | Warning | Info | Score |
|--------------|----------|---------|------|-------|
| Security     | 1        | 3       | 2    | 21    |
| Bugs         | 2        | 1       | 0    | 23    |
| Dead Code    | 0        | 4       | 6    | 18    |
| Architecture | 0        | 2       | 3    | 9     |
| Performance  | 1        | 0       | 1    | 11    |
| Total        | 4        | 10      | 12   | 82    |
```

Each finding has a unique ID (`SEC-001`, `BUG-003`), severity, file location, description, and a specific fix suggestion.

### 4. Action Plan

Findings are grouped into:
- **Quick Wins** — fix in minutes (dead imports, stale TODOs)
- **Important Fixes** — fix soon (bugs, security warnings)
- **Strategic Improvements** — plan and schedule (architecture refactors)

### 5. Surgical Fixes

After reviewing the report, you choose what to fix:

```
fix all                    # Everything
fix critical               # Only critical severity
fix security               # Only security findings
fix SEC-001, BUG-003       # Specific findings by ID
fix quick wins             # Low-risk quick wins
skip                       # Just keep the report
```

## Usage Examples

### Full audit
```bash
/audit
```

### Pre-PR security check
```bash
/audit --focus security --changed
```

### Quick cleanup before release
```bash
/audit --focus deadcode --fix
```

### Architecture review
```bash
/audit --focus architecture --severity warning
```

### Top 5 most critical issues
```bash
/audit --top 5 --severity critical
```

## Language-Agnostic

`/audit` works with **any language** Claude Code supports:

Python, JavaScript, TypeScript, Go, Rust, Java, C#, C/C++, Ruby, PHP, Swift, Kotlin, Dart, and more.

It analyzes patterns and logic, not syntax. The same command works whether you're auditing a Django backend, a React frontend, or a Rust CLI tool.

## Installation

One line:

```bash
curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/install.sh | bash
```

Or manually:

```bash
# Global (all projects)
mkdir -p ~/.claude/commands
curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/audit.md \
  -o ~/.claude/commands/audit.md

# Project-level (this repo only)
mkdir -p .claude/commands
curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/audit.md \
  -o .claude/commands/audit.md
```

Open Claude Code and run `/audit`.

## Customization

Create a `.auditignore` file (same syntax as `.gitignore`) to skip paths:

```gitignore
generated/
third_party/
tests/fixtures/
```

Common paths like `node_modules/`, `vendor/`, `dist/`, and lock files are excluded by default.

## What's Next

This is v1.0. On the roadmap:

- Trend tracking (compare health grades over time)
- Baseline mode (only report new findings)
- More granular agent configs
- Community-contributed check patterns

## Try It

- **GitHub:** [github.com/atobones/claude-audit](https://github.com/atobones/claude-audit)
- **Install:** `curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/install.sh | bash`

Star the repo if you find it useful. Issues and PRs welcome — especially ideas for new checks or agent improvements.


path: promo/reddit-post.md
content: # Title:
I built /audit — one command, 5 parallel AI agents scan your entire codebase (security, bugs, dead code, architecture, performance)

# Body:

I kept running separate linters, security scanners, and profilers, then manually cross-referencing results. Got tired of it, so I built a Claude Code skill that does everything at once.

## What it does

Type `/audit` in Claude Code. Five agents launch in parallel:

| Agent | What it checks |
|---|---|
| Security Auditor | Hardcoded secrets, injections, auth gaps, SSRF, XSS, crypto issues |
| Bug Hunter | Null refs, race conditions, resource leaks, unhandled errors, logic flaws |
| Dead Code Janitor | Unused imports/functions, commented-out code, stale TODOs, duplicates |
| Architecture Reviewer | Circular deps, SOLID/DRY violations, god classes, layer violations |
| Performance Profiler | N+1 queries, blocking async calls, memory leaks, missing caching |

Everything runs **read-only** - nothing is touched until you say so.

## Sample output

```
Audit Report
Health Grade: B- (Above Average)

| Category     | Critical | Warning | Info | Score |
|--------------|----------|---------|------|-------|
| Security     | 1        | 3       | 2    | 21    |
| Bugs         | 2        | 1       | 0    | 23    |
| Dead Code    | 0        | 4       | 6    | 18    |
| Architecture | 0        | 2       | 3    | 9     |
| Performance  | 1        | 0       | 1    | 11    |
| Total        | 4        | 10      | 12   | 82    |
```

After the report, pick what to fix:
- `fix all` / `fix critical` / `fix security` / `fix BUG-003, SEC-001`

## Flags

- `--focus security,bugs` - run only the agents you need
- `--fix` - auto-fix without asking
- `--changed` - only scan files changed since last commit (great before PRs)
- `--severity critical` - filter noise
- `--top 10` - top N issues only

Works with **any language** - Python, JS/TS, Go, Rust, Java, C#, etc.

## Install

```bash
curl -fsSL https://raw.githubusercontent.com/atobones/claude-audit/main/install.sh | bash
```

Or manually copy one file to `~/.claude/commands/audit.md`.

**GitHub:** https://github.com/atobones/claude-audit

---

Built this for my own projects, figured others might find it useful. It's v1.0 - planning to add more checks and a CI mode. Issues and PRs welcome.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)