PerfGuard -- Performance Anti-Pattern Scanner
PerfGuard scans your codebase for performance anti-patterns including N+1 queries, synchronous I/O in async code, missing pagination, unbounded loops, memory leaks, and inefficient serialization. It supports Python (Django, Flask, FastAPI, SQLAlchemy), JavaScript/TypeScript (Node.js, React, Express), Ruby (Rails), and Java (JPA/Hibernate). All scanning happens locally using regex-based pattern matching -- no code is sent to external servers.
Commands
Free Tier (No license required)
perfguard scan [file|directory]
One-shot performance anti-pattern scan.
How to execute:
bash "<SKILL_DIR>/scripts/perfguard.sh" scan [target]
What it does:
- Accepts a file path or directory (defaults to current directory)
- Auto-detects the project stack (Python, JavaScript/TypeScript, Ruby, Java)
- Finds all relevant source files (excluding .git/, node_modules/, dist/, build/, vendor/, pycache)
- Runs 40+ performance checks against each source file
- Outputs findings with: file, line number, check ID, severity, description, recommendation
- Calculates a performance score (0-100)
- Free tier: limited to scanning up to 5 source files
- Exit code 0 if score >= 70, exit code 1 if score < 70 or critical issues found
Example usage scenarios:
- "Scan my code for performance issues" -> runs
perfguard scan . - "Check for N+1 queries in my Django app" -> runs
perfguard scan . - "Find async anti-patterns in my Node.js project" -> runs
perfguard scan src/ - "Are there performance problems in this file?" -> runs
perfguard scan path/to/file.py - "Look for slow database queries" -> runs
perfguard scan .
Pro Tier ($19/user/month -- requires PERFGUARD_LICENSE_KEY)
perfguard scan [file|directory] (unlimited)
Full performance scan with no file limit and all 40+ checks enabled.
How to execute:
bash "<SKILL_DIR>/scripts/perfguard.sh" scan [target]
What it does (beyond free):
- Unlimited source file scanning
- Full 40+ performance checks including database, async, memory, and bundle patterns
- Detailed remediation advice per finding
perfguard hooks install
Install git pre-commit hooks that scan staged files for performance anti-patterns before every commit.
How to execute:
bash "<SKILL_DIR>/scripts/perfguard.sh" hooks install
What it does:
- Validates Pro+ license
- Copies lefthook config to project root
- Installs lefthook pre-commit hook
- On every commit: scans staged source files for performance anti-patterns, blocks commit if critical issues found
perfguard hooks uninstall
Remove PerfGuard git hooks.
bash "<SKILL_DIR>/scripts/perfguard.sh" hooks uninstall
perfguard report [directory]
Generate a markdown performance audit report.
bash "<SKILL_DIR>/scripts/perfguard.sh" report [directory]
What it does:
- Validates Pro+ license
- Runs full scan of the directory
- Generates a formatted markdown report with severity breakdown
- Includes per-file findings, performance score, and remediation steps
- Output written to PERFGUARD-REPORT.md
perfguard hotspots [directory]
Identify the files with the most performance anti-patterns (hot paths).
bash "<SKILL_DIR>/scripts/perfguard.sh" hotspots [directory]
What it does:
- Validates Pro+ license
- Scans all source files in the directory
- Ranks files by total anti-pattern count and severity weight
- Shows top 10 performance hotspot files with issue breakdown
- Helps prioritize which files to optimize first
Team Tier ($39/user/month -- requires PERFGUARD_LICENSE_KEY with team tier)
perfguard budget [directory]
Check code against performance budgets.
bash "<SKILL_DIR>/scripts/perfguard.sh" budget [directory]
What it does:
- Validates Team+ license
- Runs full performance scan
- Checks results against configurable thresholds: max critical issues, max total issues, minimum score
- Returns exit code 1 if any budget is exceeded
- Designed for CI/CD pipeline integration as a quality gate
perfguard trend [directory]
Show performance trend over recent git history.
bash "<SKILL_DIR>/scripts/perfguard.sh" trend [directory]
What it does:
- Validates Team+ license
- Checks out recent commits (up to 10) and runs performance scan on each
- Shows a timeline of performance scores
- Identifies whether code quality is improving or degrading
- Helps track the impact of optimizations over time
Detected Performance Anti-Patterns
PerfGuard checks for 40+ performance anti-patterns across 4 categories:
Database / ORM Patterns
| Check | Description | Severity |
|---|---|---|
| N+1 Query | Query inside a loop / loop inside a query | Critical |
| SELECT * | Using SELECT * instead of specific columns | High |
| Missing Eager Loading | No select_related/prefetch_related (Django), includes/eager_load (Rails), JOIN FETCH (JPA) | Critical |
| Unbounded Query | Query without LIMIT or pagination | High |
| Sequential Queries | Multiple queries that could be batched | Medium |
| String SQL Concatenation | Building SQL with string concatenation | Critical |
| Missing Index Hint | Complex queries without index annotations | Medium |
JavaScript / TypeScript Patterns
| Check | Description | Severity |
|---|---|---|
| Await in Loop | Sequential async operations instead of parallel | Critical |
| Missing Promise.all | Multiple independent awaits without Promise.all | High |
| Sync File I/O | readFileSync/writeFileSync in server code | High |
| JSON Clone | JSON.parse(JSON.stringify()) for deep cloning | Medium |
| Unbounded Array Ops | Large array operations without chunking | Medium |
| Memory Leak | Event listeners without cleanup | High |
| Missing Memoization | React components without useMemo/useCallback/React.memo | Medium |
| Full Lodash Import | Importing entire lodash instead of specific functions | High |
| Missing Pagination | API responses without pagination | High |
| Console in Production | console.log statements in production code | Low |
Python Patterns
| Check | Description | Severity |
|---|---|---|
| Heavy Module in Function | Importing heavy modules inside functions | Medium |
| List vs Generator | Large list comprehensions that should be generators | Medium |
| String Concat in Loop | String concatenation in loops instead of join | Medium |
| Sleep in Async | time.sleep() in async code | Critical |
| Missing Connection Pool | Direct connections without pooling | High |
| Sync in Async | Synchronous I/O in async functions | High |
| Full File Load | Loading entire files into memory | Medium |
| Regex in Loop | Compiling regex inside loops | Medium |
General Patterns
| Check | Description | Severity |
|---|---|---|
| Unbounded Retry | Retries without exponential backoff | High |
| Missing Timeout | HTTP requests without timeout | High |
| Polling | Polling instead of webhooks/events | Medium |
| Hardcoded Delay | Hardcoded sleep/delay values | Low |
| Missing Cache | Repeated computations without caching | Medium |
| No Memoization | Recursive functions without memoization | Medium |
| Large Payload | Serialization without streaming | Medium |
Configuration
Users can configure PerfGuard in ~/.openclaw/openclaw.json:
{
"skills": {
"entries": {
"perfguard": {
"enabled": true,
"apiKey": "YOUR_LICENSE_KEY_HERE",
"config": {
"severityThreshold": "high",
"excludePatterns": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
"reportFormat": "markdown"
}
}
}
}
}
Important Notes
- Free tier works immediately with no configuration (limited to 5 source files)
- All scanning happens locally -- no code is sent to external servers
- License validation is offline -- no phone-home or network calls
- Supports Python, JavaScript/TypeScript, Ruby, and Java
- Git hooks use lefthook which must be installed (see install metadata above)
- Exit codes: 0 = clean (score >= 70), 1 = issues found (for CI/CD integration)
Error Handling
- If lefthook is not installed and user tries
hooks install, prompt to install it - If license key is invalid or expired, show clear message with link to https://perfguard.pages.dev/renew
- If a file is binary, skip it automatically with no warning
- If no source files found in target, report clean scan with info message
- If project stack cannot be auto-detected, try all patterns
When to Use PerfGuard
The user might say things like:
- "Scan my code for performance issues"
- "Find N+1 queries in my app"
- "Check for async anti-patterns"
- "Are there performance problems in my code?"
- "Look for slow database queries"
- "Find memory leaks in my React app"
- "Check for missing pagination"
- "Scan for sync I/O in my server code"
- "Generate a performance report"
- "Show me performance hotspots"
- "Set up performance checks on my commits"
- "Check if code meets performance budgets"
- "Show performance trends over time"
- "Find unbounded queries"
- "Check for missing eager loading"