asyncguard

Async/await anti-pattern analyzer -- detects promise misuse, async resource leaks, event loop blocking, missing cancellation, async error patterns, and coord...

Security Scan

AsyncGuard's files, instructions, and requested license key are consistent with a local async/await anti-pattern scanner that optionally integrates with lefthook git hooks; nothing in the package indicates covert exfiltration or unrelated credential requests.

Purpose & Capability

Name/description match the delivered files and runtime behavior: shell scripts implement local pattern-based scanning, report generation, and git-hook integration. Required binaries (git, bash, python3, jq) are used by the scripts and are appropriate. The brew install of lefthook aligns with the stated git-hook feature.

Instruction Scope

SKILL.md and the scripts instruct only local actions: discovering files, running grep-based regex checks, computing scores, generating text/json/html reports, and optional hook installation. The code references only local config (~/.openclaw/openclaw.json) and local tools; there are no network calls or external endpoints invoked by the scripts.

Install Mechanism

Install spec uses a Homebrew formula (lefthook), a well-known package manager and tap. The package's own files are shipped in the skill bundle; no arbitrary downloads or remote extract/install steps are present in the provided code.

Credentials

The primary credential ASYNCGUARD_LICENSE_KEY is expected for tiered license checks and is declared. The license module also optionally reads ~/.openclaw/openclaw.json (declared in metadata) which is reasonable. One minor surprise: the license verification code conditionally uses an environment var named CLAWHUB_JWT_SECRET (not declared in requires.env) to verify JWT signatures if present — this is optional but worth noting since it's an undeclared, platform-prefixed secret that will be consulted if set.

Persistence & Privilege

always:false and normal model invocation; the skill can install lefthook git hooks (it modifies or creates lefthook.yml and runs lefthook install) which will run scans on pre-commit/pre-push in repositories. This is functionally expected for a linter but it does change repository hook state and can block commits/pushes until issues are addressed or hooks are disabled.

Assessment

This skill appears to do what it says: a purely local regex-based async pattern scanner with optional git-hook integration. Before installing: 1) Decide whether you want automatic hooks in your repos — the skill will create/append a lefthook.yml and run lefthook install which can block commits/pushes. 2) The Pro/Team features require ASYNCGUARD_LICENSE_KEY or an entry in ~/.openclaw/openclaw.json; the license code will read that file. 3) There is an optional CLAWHUB_JWT_SECRET environment variable referenced by the license verifier — only set that if you trust the signing source. 4) Review the included scripts (patterns.sh) if you want to confirm which regexes will run on your code. If you do not want hooks, avoid running the hooks install command; running one-shot scans (bash scripts/dispatcher.sh ...) remains local and safe.

AsyncGuard -- Async/Await Anti-Pattern Analyzer

AsyncGuard scans codebases for async/await anti-patterns, promise misuse, async resource leaks, event loop blocking, missing cancellation support, async error handling gaps, and coordination issues. It uses regex-based pattern matching against 90 async-specific patterns across 6 categories, lefthook for git hook integration, and produces markdown reports with actionable remediation guidance. 100% local. Zero telemetry.

Commands

Free Tier (No license required)

asyncguard scan [file|directory]

One-shot async safety scan of files or directories.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [target]

What it does:

1. Accepts a file path or directory (defaults to current directory)
2. Discovers all source files (skips .git, node_modules, binaries, images, .min.js)
3. Runs 30 async patterns against each file (free tier limit)
4. Calculates an async safety score (0-100) per file and overall
5. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (<60)
6. Outputs findings with: file, line number, check ID, severity, description, recommendation
7. Exit code 0 if score >= 70, exit code 1 if async quality is poor
8. Free tier limited to first 30 patterns (PM + AR categories)

Example usage scenarios:

• "Scan my code for async issues" -> runs asyncguard scan .
• "Check this file for promise misuse" -> runs asyncguard scan src/server.ts
• "Find resource leaks in my async code" -> runs asyncguard scan src/
• "Audit async patterns in my project" -> runs asyncguard scan .
• "Check for missing cancellation" -> runs asyncguard scan .

Pro Tier ($19/user/month -- requires ASYNCGUARD_LICENSE_KEY)

asyncguard scan --tier pro [file|directory]

Extended scan with 60 patterns covering promise misuse, resource leaks, event loop blocking, and cancellation.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [target] --tier pro

What it does:

1. Validates Pro+ license
2. Runs 60 async patterns (PM, AR, EL, CA categories)
3. Detects event loop blocking (sync I/O, sync crypto)
4. Identifies missing cancellation and abort handling
5. Full category breakdown reporting

asyncguard scan --format json [directory]

Generate JSON output for CI/CD integration.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format json

asyncguard scan --format html [directory]

Generate HTML report for browser viewing.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format html

asyncguard scan --category EL [directory]

Filter scan to a specific check category (PM, AR, EL, CA, AE, AC).

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --category EL

Team Tier ($39/user/month -- requires ASYNCGUARD_LICENSE_KEY with team tier)

asyncguard scan --tier team [directory]

Full scan with all 90 patterns across all 6 categories including async error patterns and coordination.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --tier team

What it does:

1. Validates Team+ license
2. Runs all 90 patterns across 6 categories
3. Includes async error pattern detection (swallowed rejections, async forEach, empty catch)
4. Includes coordination checks (unbounded concurrency, missing backpressure, no rate limit)
5. Full category breakdown with per-file results

asyncguard scan --verbose [directory]

Verbose output showing every matched line and pattern details.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --verbose

asyncguard status

Show license and configuration information.

bash "<SKILL_DIR>/scripts/dispatcher.sh" status

Check Categories

AsyncGuard detects 90 async anti-patterns across 6 categories:

Category	Code	Patterns	Description	Severity Range
Promise/Future Misuse	PM	15	Unhandled promises, async executor, nested .then chains, deferred antipattern	medium -- critical
Async Resource Leaks	AR	15	Unclosed connections, missing dispose, dangling streams, leaked timers	medium -- critical
Event Loop Blocking	EL	15	Sync file I/O, sync crypto, CPU loops, sync child process	low -- critical
Cancellation & Abortion	CA	15	Missing AbortSignal, orphaned tasks, no cleanup on unmount	medium -- critical
Async Error Patterns	AE	15	Swallowed rejections, empty .catch, async forEach, missing try/catch	medium -- critical
Async Coordination	AC	15	Unbounded Promise.all, missing semaphore, no backpressure, no rate limit	medium -- critical

Tier-Based Pattern Access

Tier	Patterns	Categories
Free	30	PM, AR
Pro	60	PM, AR, EL, CA
Team	90	PM, AR, EL, CA, AE, AC
Enterprise	90	PM, AR, EL, CA, AE, AC + priority support

Scoring

AsyncGuard uses a deductive scoring system starting at 100 (perfect):

Severity	Point Deduction	Description
Critical	-25 per finding	Severe async issue (resource leaks, unhandled rejections, blocking I/O)
High	-15 per finding	Significant async problem (missing cancellation, no error handler)
Medium	-8 per finding	Moderate concern (coordination issues, missing backpressure)
Low	-3 per finding	Informational / best practice suggestion

Grading Scale

Grade	Score Range	Meaning
A	90-100	Excellent async code quality
B	80-89	Good async patterns with minor issues
C	70-79	Acceptable but needs improvement
D	60-69	Poor async quality
F	Below 60	Critical async problems

• Pass threshold: 70 (Grade C or better)
• Exit code 0 = pass (score >= 70)
• Exit code 1 = fail (score < 70)

Configuration

Users can configure AsyncGuard in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "asyncguard": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "medium",
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],
          "ignoreChecks": [],
          "reportFormat": "text"
        }
      }
    }
  }
}

Important Notes

• Free tier works immediately with no configuration
• All scanning happens locally -- no code is sent to external servers
• License validation is offline -- no phone-home or network calls
• Pattern matching only -- no AST parsing, no external dependencies beyond bash
• Supports scanning all file types in a single pass
• Git hooks use lefthook which must be installed (see install metadata above)
• Exit codes: 0 = pass (score >= 70), 1 = fail (for CI/CD integration)
• Output formats: text (default), json, html

Error Handling

• If lefthook is not installed and user tries hooks, prompt to install it
• If license key is invalid or expired, show clear message with link to https://asyncguard.pages.dev/renew
• If a file is binary, skip it automatically with no warning
• If no scannable files found in target, report clean scan with info message
• If an invalid category is specified with --category, show available categories

When to Use AsyncGuard

The user might say things like:

• "Scan my code for async issues"
• "Check my promise handling"
• "Find resource leaks in async code"
• "Detect event loop blocking"
• "Are there any missing cancellation handlers?"
• "Check for unhandled promise rejections"
• "Audit my async error handling"
• "Find missing AbortController usage"
• "Check for synchronous I/O in async functions"
• "Scan for async anti-patterns"
• "Run an async code audit"
• "Generate an async safety report"
• "Check if my fetch calls have abort signals"
• "Find empty catch handlers"
• "Check my code for async coordination issues"