_ _ _ _
___ ___ __| | ___ __ _ _ _ __| (_) |_
/ __/ _ \ / _` |/ _ \/ _` | | | |/ _` | | __|
| (_| (_) | (_| | __/ (_| | |_| | (_| | | |_
\___\___/ \__,_|\___|\__,_|\__,_|\__,_|_|\__|
Run comprehensive health audits and best practices checks on any software project. Works with Claude Code, Cursor, Gemini CLI, Codex, Cline, Goose, Aider, Copilot, and Qwen.
Installation • Quick Start • Commands • How It Works • Audit Types
┌────────────────────────────────────────────────────────────┐
│ │
│ Health Audit ████████████████████ 10/10 100% │
│ │
├────────────────────────────────────────────────────────────┤
│ │
│ ● Technology Stack Detection ················· 33s │
│ ● Repository Inventory ······················· 41s │
│ ▲ Configuration & Dependencies Analysis · 82 55s │
│ ✔ Architecture Analysis ··················· 94 54s │
│ ✖ Testing Analysis ······················· 66 49s │
│ ▲ Code Quality Analysis ·················· 76 58s │
│ ✖ Security Analysis ······················ 68 49s │
│ ▲ CI/CD Analysis ························· 72 37s │
│ ▲ Documentation Analysis ················· 71 42s │
│ ▲ Report Generation & Format Enforcement · 78 4m 12s │
│ │
├────────────────────────────────────────────────────────────┤
│ Time 11m 15s │ Tokens 1.8M │ Cost ~$0.98 │
└────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────┐
│ │
│ ✔ AUDIT COMPLETE │
│ │
├────────────────────────────────────────────────────────────┤
│ │
│ Steps 10/10 passed │
│ Duration 11m 15s │
│ Tokens 1,847,203 │
│ Cost ~$0.98 │
│ │
│ Report → reports/health_audit.txt │
│ │
└────────────────────────────────────────────────────────────┘
| Feature | Description | |
|---|---|---|
| 🌐 | Universal | Works with any language — Node.js, Python, Go, Rust, Java, Kotlin, Flutter, .NET, and more |
| 🤖 | AI-Agnostic | Supports 9 AI agents: Claude Code, Cursor, Gemini, Codex, Cline, Goose, Aider, Copilot, Qwen |
| 📝 | Pure Markdown Rules | Audit rules are .md files — no proprietary format, fully transparent |
| 🔌 | Installable Skills | Install audit capabilities directly into your AI tools |
| 📊 | Detailed Reports | Generates plain-text reports ready for Google Docs |
| 🏗️ | Monorepo Aware | Automatically detects and handles monorepo structures |
| 🔒 | OWASP Security | Security analysis includes OWASP Top 10 coverage checks |
| 💰 | Token Tracking | Real-time token usage and cost estimation per step |
One-liner (recommended):
curl -fsSL https://raw.githubusercontent.com/a7asoft/codeaudit/main/install.sh | bashThis clones to ~/.codeaudit/, builds, and links the codeaudit command globally.
Manual:
git clone https://github.com/a7asoft/codeaudit.git ~/.codeaudit
cd ~/.codeaudit && npm install && npm run build
ln -sf ~/.codeaudit/dist/index.js ~/.local/bin/codeauditUpdate:
codeaudit updateUninstall:
codeaudit uninstall# 1. Check your environment
codeaudit doctor
# 2. Run a health audit on your project
cd your-project/
codeaudit run health
# 3. Run best practices check
codeaudit run practices
# 4. Specify agent and model
codeaudit run health --agent claude --model sonnet| Command | Description |
|---|---|
codeaudit run <type> |
Run an audit (health, practices) |
codeaudit doctor |
Check environment and AI tool availability |
codeaudit list |
List available audit types and their steps |
codeaudit init |
Detect AI tools and install audit skills to all |
codeaudit install <agent> |
Install skills to a specific agent |
codeaudit update |
Update codeaudit to the latest version |
codeaudit uninstall |
Remove codeaudit from your system |
| Flag | Description |
|---|---|
-a, --agent <agent> |
AI agent to use (claude, cursor, gemini, codex, cline, goose, aider, copilot, qwen) |
-m, --model <model> |
Model to use (sonnet, opus, haiku, etc.) |
-V, --version |
Show version number |
-h, --help |
Show help |
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ plan.md │────▶│ AI Agent │────▶│ Artifacts │
│ (10 steps) │ │ (Claude/ │ │ (.md files │
│ │ │ Cursor/ │ │ per step) │
└─────────────┘ │ Gemini) │ └──────┬──────┘
└─────────────┘ │
▼
┌─────────────┐
│ Report │
│ (.txt file │
│ for Docs) │
└─────────────┘
- Parse
plan.md— ordered list of audit steps - Detect AI agent — finds available CLI (9 supported agents)
- Execute each step — spawns AI process with the rule
.mdfile - Inject prior artifacts — each step gets context from completed steps
- Generate report — compiles all artifacts into final plain-text report
Each rule is a self-contained markdown file that any AI can read and follow. The CLI orchestrates execution, tracks tokens, and compiles the final report.
codeaudit run health
Comprehensive project health assessment across 9 weighted sections. Produces a 15-section report with Evidence, Risks, and Metrics per section.
Section Weight What It Checks
───────────────────────── ────── ─────────────────────────────
Technology Stack & Config 15% Language, framework, configs
Architecture 18% Patterns, layers, SOLID, DI
Code Quality 15% Linting, formatting, complexity
Testing 15% Coverage, quality, anti-patterns
Security 12% Secrets, auth, OWASP Top 10
API & Data Layer 10% API design, DB patterns
CI/CD 5% Pipelines, automation
Documentation 5% README, API docs, inline docs
Developer Experience 5% Onboarding, tooling
Output: ./reports/health_audit.txt
codeaudit run practices
Deep code-level quality assessment with file:line violation tracking.
Section Weight What It Checks
───────────────────────── ────── ─────────────────────────────
Testing Quality 35% AAA patterns, mocks, edge cases
Architecture Compliance 35% Layer boundaries, imports, DI
Code Standards 30% Naming, error handling, types
Output: ./reports/practices_audit.txt
██████████████████████████████ Strong 85-100 Excellent
████████████████████░░░░░░░░░ Fair 70-84 Good, room to improve
██████████████░░░░░░░░░░░░░░░ Weak 0-69 Needs attention
The audit is evidence-based and aggressive — scores are backed by specific file:line references, grep results, and verified config values. Hard score caps prevent inflated results:
- Hardcoded secrets found → max 30/100 on Security
- Test ratio below 15% → max 55/100 on Testing
- Empty catch blocks > 5 → -10 points on Error Handling
- No dependency scanning → max 8/15 on Dep Security
| Agent | Command | Models |
|---|---|---|
| Claude Code | --agent claude |
sonnet, opus, haiku |
| Cursor | --agent cursor |
sonnet, gpt-4o, gemini-pro |
| Gemini CLI | --agent gemini |
gemini-2.5-pro, gemini-2.5-flash |
| OpenAI Codex | --agent codex |
gpt-5.2-codex, gpt-5-codex, o3, o4-mini |
| Cline | --agent cline |
claude-sonnet-4-5, gpt-4o, gemini-2.5-pro |
| Goose | --agent goose |
claude-sonnet-4-5, gpt-4o, gemini-2.5-pro |
| Aider | --agent aider |
claude-sonnet-4-5, gpt-4o, deepseek-chat |
| GitHub Copilot | --agent copilot |
claude-sonnet-4, gpt-5 |
| Qwen Code | --agent qwen |
qwen3-coder, qwen3-coder-next |
codeaudit/
├── src/
│ ├── index.ts # CLI entry point (commander)
│ ├── commands/ # run, doctor, list, init, install, update, uninstall
│ ├── agents/ # Agent detection, resolution, installers
│ ├── runner/ # Plan parser, step executor, token tracker
│ └── utils/ # Logger, banner, progress panel
├── rules/
│ ├── health/ # 10-step health audit rules
│ │ ├── plan.md
│ │ ├── 00-stack-detector.md
│ │ ├── ...
│ │ ├── 09-report-generator.md
│ │ └── templates/
│ └── practices/ # 4-step best practices rules
│ ├── plan.md
│ ├── 00-testing-quality.md
│ ├── ...
│ ├── 03-report-generator.md
│ └── templates/
└── test/
- Node.js >= 18
- At least one AI CLI installed:
- Claude Code (recommended)
- Cursor
- Gemini CLI
- OpenAI Codex
- Cline
- Goose
- Aider
- GitHub Copilot
- Qwen Code
git clone https://github.com/a7asoft/codeaudit.git
cd codeaudit
npm install
npm run build # Build with tsup
npm run dev -- doctor # Run in dev mode
npm test # Run testsContributions are welcome! Feel free to open issues or submit pull requests.
The rule files in rules/ are plain markdown — you can improve audit quality just by editing .md files, no TypeScript needed.
Made with AI, for AI-powered development.
MIT License