perfguard

Performance anti-pattern scanner — finds N+1 queries, sync I/O, missing pagination, and memory leaks before they hit production

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:

1. Accepts a file path or directory (defaults to current directory)
2. Auto-detects the project stack (Python, JavaScript/TypeScript, Ruby, Java)
3. Finds all relevant source files (excluding .git/, node_modules/, dist/, build/, vendor/, pycache)
4. Runs 40+ performance checks against each source file
5. Outputs findings with: file, line number, check ID, severity, description, recommendation
6. Calculates a performance score (0-100)
7. Free tier: limited to scanning up to 5 source files
8. 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):

1. Unlimited source file scanning
2. Full 40+ performance checks including database, async, memory, and bundle patterns
3. 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:

1. Validates Pro+ license
2. Copies lefthook config to project root
3. Installs lefthook pre-commit hook
4. 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:

1. Validates Pro+ license
2. Runs full scan of the directory
3. Generates a formatted markdown report with severity breakdown
4. Includes per-file findings, performance score, and remediation steps
5. 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:

1. Validates Pro+ license
2. Scans all source files in the directory
3. Ranks files by total anti-pattern count and severity weight
4. Shows top 10 performance hotspot files with issue breakdown
5. 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:

1. Validates Team+ license
2. Runs full performance scan
3. Checks results against configurable thresholds: max critical issues, max total issues, minimum score
4. Returns exit code 1 if any budget is exceeded
5. 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:

1. Validates Team+ license
2. Checks out recent commits (up to 10) and runs performance scan on each
3. Shows a timeline of performance scores
4. Identifies whether code quality is improving or degrading
5. 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"