Skip to main content
command CX Codex

audit-project — Claude Code command: review and install

audit-project is a Claude Code command that reviews projects with specialized agents and can apply fixes before rechecking changed files. It helps find issues in code and tests.

MIT ★ 2,003 updated 2026-07-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add composio-community/awesome-claude-plugins
/plugin install audit-project@awesome-claude-plugins
Open on GitHub

What audit-project does

The command detects project characteristics and selects reviewers for code quality, security, performance, and tests. Other agents are chosen when the project contains signals such as a database, frontend, or CI configuration. Findings include a file location, severity, explanation, and suggested remedy.

It can apply fixes, run tests, a linter, and a build, then review changed files again. The --quick flag limits the run to one pass, with no iteration. When a fix needs a design decision, the command marks it blocked and reports it to you.

Pass a path to set the review scope, use --recent for the last five commits, or select one reviewer with --domain. The --resume flag continues from an existing review queue; --create-tech-debt requests a TECHNICAL_DEBT.md file. A fix that fails verification can be rolled back with git restore <file>.

What it helps with

  • find security and input-validation issues
  • check test quality and flag missing tests
  • spot performance bottlenecks
  • apply suggested fixes and re-review changed files
  • track findings in TECHNICAL_DEBT.md

Example prompts for the agent

  • Review the project for security issues and fix what you can: /audit-project --domain security.
  • Check only recent changes in a single pass: /audit-project --recent --quick.
  • Resume the existing review queue and update TECHNICAL_DEBT.md: /audit-project --resume --create-tech-debt.

How to install audit-project

1Plugin marketplace

/plugin marketplace add composio-community/awesome-claude-plugins
/plugin install audit-project@awesome-claude-plugins

2Manually: put the files in place

.claude/commands/audit-project.md

Call it with /audit-project. For all projects use ~/.claude/commands/

Questions about audit-project

How do I install audit-project in Claude Code?

Run /plugin marketplace add composio-community/awesome-claude-plugins, then /plugin install audit-project@awesome-claude-plugins.

What does audit-project do?

It coordinates specialist agents to review a project, records findings, and can apply fixes followed by tests, linting, and a build.

What does the --quick flag do?

It runs a single review pass without the fix-and-review cycle.

Source text

audit-project.md · MIT
---
description: Multi-agent code review with iterative improvement
argument-hint: "[scope] [--recent] [--domain AGENT] [--quick] [--create-tech-debt] [--resume]"
allowed-tools: Bash(git:*), Bash(node:*), Read, Write, Edit, Glob, Grep, Task, AskUserQuestion
---

# /audit-project - Multi-Agent Code Review

Comprehensive code review using specialized AI agents with iterative improvement.

## Quick Reference

| Phase | Description | Details |
|-------|-------------|---------|
| 1 | Context & Agent Selection | This file |
| 2 | Multi-Agent Review | See `audit-project-agents.md` |
| 3-4 | Tech Debt & Fixes | This file |
| 5-6 | Verification & Iteration | This file |
| 7 | Completion Report | This file |
| 8 | GitHub Issues | See `audit-project-github.md` |

## Arguments

Parse from $ARGUMENTS:
- **Scope**: Path to review (default: `.`) or `--recent` (last 5 commits only)
- **--domain AGENT**: Review with specific agent only (e.g., `--domain security`)
- **--quick**: Single pass, no iteration (fast feedback)
- **--create-tech-debt**: Force create/update TECHNICAL_DEBT.md
- **--resume**: Resume from existing review queue file

### Resume Mode

If `--resume` is provided, reuse the most recent review queue in the platform state dir.
Otherwise create a new queue file. See `audit-project-agents.md` for queue handling.

## Phase 1: Context Gathering

### Platform Detection

```bash
# Get plugin root using Node.js helper
PLUGIN_ROOT=$(node -e "const { getPluginRoot } = require('@awesome-slash/lib/cross-platform'); const root = getPluginRoot('audit-project'); if (!root) { console.error('Error: Could not locate audit-project plugin root'); process.exit(1); } console.log(root);")
PLATFORM=$(node "$PLUGIN_ROOT/lib/platform/detect-platform.js")
TOOLS=$(node "$PLUGIN_ROOT/lib/platform/verify-tools.js")

PROJECT_TYPE=$(echo $PLATFORM | jq -r '.projectType')
PACKAGE_MGR=$(echo $PLATFORM | jq -r '.packageManager')

# Detect framework
FRAMEWORK="unknown"
if [ "$PROJECT_TYPE" = "nodejs" ]; then
  [ -n "$(jq -e '.dependencies.react' package.json 2>/dev/null)" ] && FRAMEWORK="react"
  [ -n "$(jq -e '.dependencies.express' package.json 2>/dev/null)" ] && FRAMEWORK="express"
elif [ "$PROJECT_TYPE" = "python" ]; then
  grep -q "django" requirements.txt 2>/dev/null && FRAMEWORK="django"
  grep -q "fastapi" requirements.txt 2>/dev/null && FRAMEWORK="fastapi"
fi

RESUME_MODE=$([ "${ARGUMENTS}" != "${ARGUMENTS%--resume*}" ] && echo "true" || echo "false")
```

### Project Analysis

```bash
FILE_COUNT=$(git ls-files | wc -l)
TEST_FILES=$(git ls-files | grep -E '(test|spec)\.' | wc -l)
HAS_TESTS=$( [ "$TEST_FILES" -gt 0 ] && echo "true" || echo "false" )
HAS_DB=$(grep -rq -E "(Sequelize|Prisma|TypeORM)" . 2>/dev/null && echo "true" || echo "false")
HAS_API=$(grep -rq -E "(express|fastify|@nestjs)" . 2>/dev/null && echo "true" || echo "false")
HAS_FRONTEND=$( [ "$(git ls-files | grep -E '\.(tsx|jsx|vue|svelte)$' | wc -l)" -gt 0 ] && echo "true" || echo "false" )
HAS_BACKEND=$(grep -rq -E "(express|fastify|@nestjs|koa|hapi)" . 2>/dev/null && echo "true" || echo "false")
if [ -d ".github/workflows" ] || [ -f ".gitlab-ci.yml" ] || [ -f ".circleci/config.yml" ] || \
  [ -f "Jenkinsfile" ] || [ -f ".travis.yml" ] || [ -f "azure-pipelines.yml" ] || \
  [ -f "bitbucket-pipelines.yml" ]; then
  HAS_CICD="true"
else
  HAS_CICD="false"
fi
```

### Agent Selection

**Always Active:**
- `code-quality-reviewer`: Code quality, error handling, maintainability
- `security-expert`: Security vulnerabilities, auth, input validation
- `performance-engineer`: Performance bottlenecks, algorithms, memory
- `test-quality-guardian`: Test coverage and quality (reports missing tests)

**Conditional:**
- `architecture-reviewer`: Design patterns (if `FILE_COUNT > 50`)
- `database-specialist`: Query optimization (if `HAS_DB=true`)
- `api-designer`: REST best practices (if `HAS_API=true`)
- `frontend-specialist`: Component design (if `HAS_FRONTEND=true`)
- `backend-specialist`: Service and domain logic (if `HAS_BACKEND=true`)
- `devops-reviewer`: CI/CD config (if `HAS_CICD=true`)

## Phase 2: Multi-Agent Review

See `audit-project-agents.md` for detailed agent coordination.

**Review queue:** Write findings to a temporary queue file in the platform state dir and keep it updated until all issues are resolved. Remove the file when the queue is empty.

### Finding Format (Required)

Every finding MUST include:
- **File:Line**: Exact location (e.g., `src/auth/session.ts:42`)
- **Severity**: critical | high | medium | low
- **Category**: From agent domain
- **Description**: What's wrong and why
- **Code Quote**: 1-3 lines showing issue
- **Suggested Fix**: Specific remediation
- **Effort**: small | medium | large

### Example Finding

```markdown
### Finding: Unsafe SQL Query
**Agent**: security-expert
**File**: src/api/users.ts:87
**Severity**: critical
**Code**:
```typescript
const query = `SELECT * FROM users WHERE id = ${userId}`;
```
**Fix**: Use parameterized queries.
**Effort**: small
```

## Phase 3: Tech Debt Documentation

If TECHNICAL_DEBT.md exists or `--create-tech-debt`:

```markdown
# Technical Debt

Last updated: $(date -I)

## Summary
**Total Issues**: X | Critical: Y | High: Z | Medium: A | Low: B

## Critical Issues
[Grouped by severity with file:line, description, fix, effort]

## Progress Tracking
- [ ] Issue 1
- [ ] Issue 2
```

## Phase 4: Automated Fixes

### Fix Strategy

1. **Auto-fixable** (lint, formatting): Apply directly
2. **Manual fix** (code logic): Implement suggested fix
3. **Design decision required**: Flag as blocked and report to user
4. **False positive**: Mark and remove from review queue

### Fix Order

1. Critical severity first
2. Then high → medium → low
3. Then by effort (small → large)
4. Then batch by file

## Phase 5: Verification

```bash
# Run tests
[ -n "$TEST_CMD" ] && $TEST_CMD
TEST_STATUS=$?

# Run linter
[ -n "$LINT_CMD" ] && $LINT_CMD
LINT_STATUS=$?

# Run build
[ -n "$BUILD_CMD" ] && $BUILD_CMD
BUILD_STATUS=$?

# Overall status
VERIFICATION_PASSED=$([ $TEST_STATUS -eq 0 ] && [ $LINT_STATUS -eq 0 ] && [ $BUILD_STATUS -eq 0 ] && echo "true" || echo "false")
```

### Handle Failures

If verification fails:
1. Review recent changes (`git diff`)
2. Identify breaking fix
3. Rollback: `git restore <file>`
4. Document as "fix caused regression"

## Phase 6: Iteration

```javascript
const initialReview = /* results from Phase 2 review */;
const initialIssues = Array.isArray(initialReview?.issues) ? initialReview.issues : [];
let iteration = 1;
let remainingIssues = initialIssues;

while (remainingIssues.length > 0) {
  const fixResult = applyFixes(remainingIssues);

  const verifyResult = runVerification();
  if (!verifyResult.passed) {
    rollbackFailed(fixResult);
  }

  const reReviewResult = reReview(fixResult.changedFiles);
  remainingIssues = reReviewResult.issues;

  if (remainingIssues.length === 0) {
    console.log("[OK] Zero issues remaining!");
    break;
  }

  iteration++;
}
```

### Quick Mode

If `--quick` flag: Single pass, findings only, no fixes.

## Phase 6.5: Decision Gate (User)

After each iteration (or after re-review if issues remain), report the queue state and ask the user what to do next.

```javascript
const openCount = remainingIssues.length;
console.log(`Open issues: ${openCount}`);
console.log(`Queue file: ${reviewQueuePath}`); // set in Phase 2 (audit-project-agents)

const decision = await AskUserQuestion({
  questions: [{
    header: "Audit Decision",
    question: "Review queue still open. What next?",
    options: [
      { label: "Continue review", description: "Run another iteration" },
      { label: "Create issues", description: "Stop and create issues" },
      { label: "Update tech debt", description: "Stop and update TECHNICAL_DEBT.md" },
      { label: "Leave queue", description: "Stop and keep queue for resume" }
    ],
    multiSelect: false
  }]
});

const choice = decision[0];
if (choice === 'Continue review') {
  // continue loop
} else if (choice === 'Create issues') {
  // Create issues and remove queue file
} else if (choice === 'Update tech debt') {
  // Update TECHNICAL_DEBT.md and remove queue file
} else if (choice === 'Leave queue') {
  // Leave queue file for --resume
  break;
}
```

## Phase 7: Completion Report

```markdown
# Project Review Complete

**Scope**: ${SCOPE} | **Framework**: ${FRAMEWORK}
**Iterations**: ${iteration} | **Duration**: ${duration}

## Summary
**Issues Found**: ${initialCount}
**Issues Fixed**: ${fixedCount}
**Remaining**: ${remainingCount}

## By Severity
- Critical: ${criticalFound} → ${criticalRemaining}
- High: ${highFound} → ${highRemaining}
- Medium: ${mediumFound} → ${mediumRemaining}
- Low: ${lowFound} → ${lowRemaining}

## Verification
- Tests: [OK]/[FAIL]
- Linter: [OK]/[FAIL]
- Build: [OK]/[FAIL]

## Files Changed
${FILE_COUNT} files modified

## Remaining Issues
[List of issues needing attention]
```

## Phase 8: GitHub Issue Creation

See `audit-project-github.md` for:
- Creating GitHub issues for deferred items
- Security issue handling (no public issues)
- TECHNICAL_DEBT.md cleanup

## Error Handling

### No Framework Detected
```
Framework detection failed, using generic patterns.
```

### No Tests Available
```
No test suite detected. Skipping test-quality-guardian.
```

### All Agents Failed
```
ERROR: All review agents failed.
Try: --recent or specific path for smaller scope.
```

## Usage Examples

```bash
/audit-project                    # Full review
/audit-project --recent           # Last 5 commits only
/audit-project src/api            # Specific path
/audit-project --domain security  # Security audit only
/audit-project --quick            # Fast feedback, no fixes
/audit-project --create-tech-debt # Force tech debt file
```

## Success Criteria

- [OK] All agents completed review
- [OK] Evidence-based findings (file:line provided)
- [OK] Critical issues fixed or documented
- [OK] Verification passes
- [OK] TECHNICAL_DEBT.md updated (if enabled)

Begin Phase 1 now.

© Community · MIT · composio-community/awesome-claude-plugins

Similar slash commands

All slash commands for Code review and refactoring →

From the same set68

The whole set →
frontend-developer The frontend-developer subagent for Claude Code builds responsive components in React, Vue, or Angular and tunes frontend rendering performance. CX Codex ★ 2,003repo stars add-sub add-sub creates a skill-event subscription, so context lands before or after a skill runs, gated on files, git branch or environment variables. CX Codex +1 ★ 2,003repo stars ship-deployment The ship-deployment command completes the deployment half of /ship: it tracks Railway, Vercel or Netlify releases through dev checks and production, and reverts the merge if production fails. CX Codex +1 ★ 2,003repo stars test-writer-fixer test-writer-fixer creates missing test suites, runs test runners after code changes, and updates failing checks. It keeps your test suite aligned with refactored logic. CX Codex ★ 2,003repo stars help help prints skill-bus status plus its slash-command list. Add advanced to get the longer reference on settings and conditions. CX Codex +1 ★ 2,003repo stars onboard The onboard command for Claude Code configures skill-bus by discovering repository documents, routing them to skills through subscriptions, and enabling local telemetry. CX Codex +1 ★ 2,003repo stars perf-orchestrator perf-orchestrator coordinates performance investigations from baseline measurements through profiling and validation. Keeps each phase sequential and logged. CX Codex ★ 2,003repo stars audit-project-agents audit-project-agents sends a whole codebase to specialised review agents, each on its own slice of files, and collects their findings in one queue. CX Codex +1 ★ 2,003repo stars

Project sponsors

Companies that keep this analytics open