\r \r

ConcurrencyGuard -- Race Condition & Concurrency Safety Analyzer\r

\r ConcurrencyGuard scans codebases for concurrency hazards: unprotected shared state, missing mutex/locks, TOCTOU vulnerabilities, async/await pitfalls, thread-unsafe singletons, missing transaction isolation, data races in goroutines, unguarded lazy initialization, non-atomic read-modify-write, and deadlock-prone lock ordering -- across JS/TS, Python, Java, Go, Rust, and C#. It uses regex-based pattern matching against 90+ concurrency safety patterns, lefthook for git hook integration, and produces markdown reports with actionable remediation recommendations. 100% local. Zero telemetry.\r \r

Commands\r

\r

Free Tier (No license required)\r

\r

concurrencyguard scan [file|directory]\r

One-shot concurrency safety scan of files or directories.\r \r How to execute:\r

bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" scan [target]\r
```\r
\r
**What it does:**\r
1. Accepts a file path or directory (defaults to current directory)\r
2. Discovers all source files (skips .git, node_modules, binaries, images, .min.js)\r
3. Runs 90+ concurrency safety patterns against each file\r
4. Respects .gitignore and allowlist files\r
5. Calculates a concurrency safety score (0-100) per file and overall\r
6. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (\x3C60)\r
7. Outputs findings with: file, line number, check ID, severity, description, recommendation\r
8. Exit code 0 if score >= 70, exit code 1 if too many issues found\r
9. Free tier limited to 5 files per scan\r
\r
**Example usage scenarios:**\r
- "Scan my code for race conditions" -> runs `concurrencyguard scan .`\r
- "Check this file for concurrency issues" -> runs `concurrencyguard scan src/server.go`\r
- "Find thread safety problems in my project" -> runs `concurrencyguard scan src/`\r
- "Are there any deadlock risks in my code?" -> runs `concurrencyguard scan .`\r
- "Check for missing locks" -> runs `concurrencyguard scan .`\r
- "Find TOCTOU vulnerabilities" -> runs `concurrencyguard scan .`\r
\r
#### `concurrencyguard hook install`\r
Install git pre-commit hooks that scan staged files for concurrency issues before every commit.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" hook install\r
```\r
\r
**What it does:**\r
1. Copies lefthook config to project root\r
2. Installs lefthook pre-commit hook\r
3. On every commit: scans all staged files for concurrency hazards, blocks commit if critical/high findings, shows remediation advice\r
\r
#### `concurrencyguard hook uninstall`\r
Remove ConcurrencyGuard git hooks.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" hook uninstall\r
```\r
\r
#### `concurrencyguard report [directory]`\r
Generate a markdown concurrency safety report with findings, severity breakdown, and remediation steps.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" report [directory]\r
```\r
\r
**What it does:**\r
1. Runs full scan of the directory\r
2. Generates a formatted markdown report from template\r
3. Includes per-file breakdowns, concurrency safety scores, remediation priority\r
4. Output suitable for code reviews and architecture audits\r
\r
### Pro Tier ($19/user/month -- requires CONCURRENCYGUARD_LICENSE_KEY)\r
\r
#### `concurrencyguard watch [directory]`\r
Continuous file-watching mode that re-scans on every file change.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" watch [directory]\r
```\r
\r
**What it does:**\r
1. Validates Pro+ license\r
2. Watches directory for file changes using filesystem events\r
3. Re-scans changed files automatically\r
4. Reports new concurrency issues in real time\r
5. Ideal for active development sessions\r
\r
#### `concurrencyguard ci [directory]`\r
CI/CD integration mode with strict exit codes and machine-readable output.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" ci [directory]\r
```\r
\r
**What it does:**\r
1. Validates Pro+ license\r
2. Runs full scan of the directory\r
3. Outputs machine-readable results with exit codes for CI systems\r
4. Exit 0 = clean, exit 1 = critical/high issues, exit 2 = medium issues\r
5. Compatible with GitHub Actions, GitLab CI, Jenkins, CircleCI\r
\r
### Team Tier ($39/user/month -- requires CONCURRENCYGUARD_LICENSE_KEY with team tier)\r
\r
#### `concurrencyguard team-report [directory]`\r
Generate an aggregate team-level concurrency safety report with trend data.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" team-report [directory]\r
```\r
\r
**What it does:**\r
1. Validates Team+ license\r
2. Runs full scan with aggregation by module/package\r
3. Generates team-level metrics (hotspot files, worst categories, trend indicators)\r
4. Includes per-developer breakdown when git blame data is available\r
5. Suitable for sprint retrospectives and architecture reviews\r
\r
#### `concurrencyguard baseline [directory]`\r
Establish a baseline of known concurrency issues for allowlisting.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" baseline [directory]\r
```\r
\r
**What it does:**\r
1. Validates Team+ license\r
2. Scans directory and records all current findings as baseline\r
3. Saves baseline to .concurrencyguard-baseline.json\r
4. Future scans only report NEW issues not in the baseline\r
5. Useful for legacy codebases with known accepted concurrency patterns\r
\r
#### `concurrencyguard status`\r
Show license and configuration information.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/concurrencyguard.sh" status\r
```\r
\r
## Detected Concurrency Patterns\r
\r
ConcurrencyGuard detects 90+ concurrency safety patterns across 6 categories:\r
\r
| Category | Examples | Severity |\r
|----------|----------|----------|\r
| **Shared State (SS)** | Global mutable variables, unprotected static fields, module-level mutable state, shared variables without volatile/atomic, global object mutation in worker threads | Critical/High |\r
| **Locking & Mutex (LK)** | Missing synchronized in Java, missing lock in C#, missing mutex.Lock() in Go, Lock without Unlock, nested locks (deadlock risk), missing RWMutex, spin locks in user code | Critical/High |\r
| **TOCTOU & Atomicity (TC)** | Check-then-act without synchronization, file exists then open, read-modify-write without CAS, double-checked locking without volatile, non-atomic counters | Critical/High |\r
| **Async/Await Pitfalls (AW)** | Await in loop (sequential not parallel), missing await, async void, fire-and-forget promises, race conditions after await, missing Promise.all | High/Medium |\r
| **Thread Safety (TS)** | Thread-unsafe singleton, HashMap without sync, non-thread-safe datetime, mutable defaults shared across threads, lazy init without double-check | High/Medium |\r
| **Deadlock & Starvation (DL)** | Inconsistent lock ordering, holding lock across external call, channel without timeout, unbuffered channel in goroutine, missing select/default, lock held across await | Critical/High |\r
\r
## Configuration\r
\r
Users can configure ConcurrencyGuard in `~/.openclaw/openclaw.json`:\r
\r
```json\r
{\r
  "skills": {\r
    "entries": {\r
      "concurrencyguard": {\r
        "enabled": true,\r
        "apiKey": "YOUR_LICENSE_KEY_HERE",\r
        "config": {\r
          "severityThreshold": "high",\r
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],\r
          "ignoreChecks": [],\r
          "allowlistFile": ".concurrencyguard-allowlist",\r
          "reportFormat": "markdown"\r
        }\r
      }\r
    }\r
  }\r
}\r
```\r
\r
## Important Notes\r
\r
- **Free tier** works immediately with no configuration\r
- **All scanning happens locally** -- no code is sent to external servers\r
- **License validation is offline** -- no phone-home or network calls\r
- Pattern matching only -- no AST parsing, no external dependencies beyond bash\r
- Supports scanning JS/TS, Python, Java, Go, Rust, and C# in a single pass\r
- Git hooks use **lefthook** which must be installed (see install metadata above)\r
- Exit codes: 0 = clean (score >= 70), 1 = issues detected (for CI/CD integration)\r
\r
## Error Handling\r
\r
- If lefthook is not installed and user tries `hook install`, prompt to install it\r
- If license key is invalid or expired, show clear message with link to https://concurrencyguard.pages.dev/renew\r
- If a file is binary, skip it automatically with no warning\r
- If no scannable files found in target, report clean scan with info message\r
- If .concurrencyguard-allowlist is missing, skip allowlist filtering gracefully\r
\r
## When to Use ConcurrencyGuard\r
\r
The user might say things like:\r
- "Scan my code for race conditions"\r
- "Find concurrency bugs in my project"\r
- "Check for thread safety issues"\r
- "Are there any deadlock risks in my code?"\r
- "Scan for missing locks or mutexes"\r
- "Find TOCTOU vulnerabilities"\r
- "Check my async/await code for pitfalls"\r
- "Find unprotected shared state"\r
- "Detect data races in my Go code"\r
- "Check for thread-unsafe singletons"\r
- "Scan for concurrency issues before I push"\r
- "Set up pre-commit hooks for concurrency checking"\r
- "Generate a concurrency safety report"\r
- "Find missing synchronization in my Java code"\r
- "Check for non-atomic operations"\r
- "Detect deadlock-prone lock ordering"\r