concurrencyguard

ConcurrencyGuard -- Race Condition & Concurrency Safety Analyzer

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.

Commands

Free Tier (No license required)

#### concurrencyguard scan [file|directory] One-shot concurrency safety scan of files or directories.

How to execute:

bash "/scripts/concurrencyguard.sh" scan [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 90+ concurrency safety patterns against each file 4. Respects .gitignore and allowlist files 5. Calculates a concurrency safety score (0-100) per file and overall 6. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (<60) 7. Outputs findings with: file, line number, check ID, severity, description, recommendation 8. Exit code 0 if score >= 70, exit code 1 if too many issues found 9. Free tier limited to 5 files per scan

Example usage scenarios:

#### concurrencyguard hook install Install git pre-commit hooks that scan staged files for concurrency issues before every commit.

How to execute:

bash "/scripts/concurrencyguard.sh" hook install

What it does: 1. Copies lefthook config to project root 2. Installs lefthook pre-commit hook 3. On every commit: scans all staged files for concurrency hazards, blocks commit if critical/high findings, shows remediation advice

#### concurrencyguard hook uninstall Remove ConcurrencyGuard git hooks.

bash "/scripts/concurrencyguard.sh" hook uninstall

#### concurrencyguard report [directory] Generate a markdown concurrency safety report with findings, severity breakdown, and remediation steps.

bash "/scripts/concurrencyguard.sh" report [directory]

What it does: 1. Runs full scan of the directory 2. Generates a formatted markdown report from template 3. Includes per-file breakdowns, concurrency safety scores, remediation priority 4. Output suitable for code reviews and architecture audits

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

#### concurrencyguard watch [directory] Continuous file-watching mode that re-scans on every file change.

bash "/scripts/concurrencyguard.sh" watch [directory]

What it does: 1. Validates Pro+ license 2. Watches directory for file changes using filesystem events 3. Re-scans changed files automatically 4. Reports new concurrency issues in real time 5. Ideal for active development sessions

#### concurrencyguard ci [directory] CI/CD integration mode with strict exit codes and machine-readable output.

bash "/scripts/concurrencyguard.sh" ci [directory]

What it does: 1. Validates Pro+ license 2. Runs full scan of the directory 3. Outputs machine-readable results with exit codes for CI systems 4. Exit 0 = clean, exit 1 = critical/high issues, exit 2 = medium issues 5. Compatible with GitHub Actions, GitLab CI, Jenkins, CircleCI

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

#### concurrencyguard team-report [directory] Generate an aggregate team-level concurrency safety report with trend data.

bash "/scripts/concurrencyguard.sh" team-report [directory]

What it does: 1. Validates Team+ license 2. Runs full scan with aggregation by module/package 3. Generates team-level metrics (hotspot files, worst categories, trend indicators) 4. Includes per-developer breakdown when git blame data is available 5. Suitable for sprint retrospectives and architecture reviews

#### concurrencyguard baseline [directory] Establish a baseline of known concurrency issues for allowlisting.

bash "/scripts/concurrencyguard.sh" baseline [directory]

What it does: 1. Validates Team+ license 2. Scans directory and records all current findings as baseline 3. Saves baseline to .concurrencyguard-baseline.json 4. Future scans only report NEW issues not in the baseline 5. Useful for legacy codebases with known accepted concurrency patterns

#### concurrencyguard status Show license and configuration information.

bash "/scripts/concurrencyguard.sh" status

Detected Concurrency Patterns

ConcurrencyGuard detects 90+ concurrency safety patterns across 6 categories:

| Category | Examples | Severity | |----------|----------|----------| | 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 | | 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 | | 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 | | 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 | | 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 | | 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 |

Configuration

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

{
  "skills": {
    "entries": {
      "concurrencyguard": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "high",
          "ignorePatterns": ["/test/", "/fixtures/", "**/*.test.*"],
          "ignoreChecks": [],
          "allowlistFile": ".concurrencyguard-allowlist",
          "reportFormat": "markdown"
        }
      }
    }
  }
}

Important Notes

Error Handling

When to Use ConcurrencyGuard

The user might say things like:

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

{
  "skills": {
    "entries": {
      "concurrencyguard": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "high",
          "ignorePatterns": ["/test/", "/fixtures/", "**/*.test.*"],
          "ignoreChecks": [],
          "allowlistFile": ".concurrencyguard-allowlist",
          "reportFormat": "markdown"
        }
      }
    }
  }
}