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"