# One command to catch 1000+ bug patterns (always master, cache-busted)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" \
| bash -s --

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" \
| bash -s -- --easy-mode

🔬 Ultimate Bug Scanner v5.0

The AI Coding Agent’s Secret Weapon: Flagging Likely Bugs for Fixing Early On

# One command to catch 1000+ bug patterns (always master, cache-busted)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" \
| bash -s --

---

Just want it to do everything without confirmations? Live life on the edge with easy-mode to auto-install every dependency, accept all prompts, detect local coding agents, and wire their quality guardrails with zero extra questions:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" \
| bash -s -- --easy-mode

Note: Windows users must run the installer one-liner from within Git Bash, or use WSL for Windows.

💥 The Problem: AI Moves Fast, Bugs Move Faster

You’re coding faster than ever with Claude Code, Codex, Cursor, and other AI coding agents. You’re shipping features in minutes that used to take days. But here’s the painful truth:

Even the best AI makes these mistakes:

JavaScript/TypeScript example (similar patterns exist in Python, Go, Rust, Java, C++, Ruby):

// ❌ CRITICAL BUG #1: Null pointer crash waiting to happen
const submitButton = document.getElementById('submit');
submitButton.addEventListener('click', handleSubmit);  // 💥 Crashes if element doesn't exist

// ❌ CRITICAL BUG #2: XSS vulnerability
function displayUserComment(comment) {
document.getElementById('comments').innerHTML = comment;  // 🚨 Security hole
}

// ❌ CRITICAL BUG #3: Silent failure (missing await)
async function saveUser(data) {
const result = validateUser(data);  // 💥 Should be 'await validateUser(data)'
await saveToDatabase(result);  // Saves undefined!
}

// ❌ CRITICAL BUG #4: Always false comparison
if (calculatedValue === NaN) {  // 💥 This NEVER works (always false)
console.log("Invalid calculation");
}

// ❌ CRITICAL BUG #5: parseInt footgun
const zipCode = parseInt(userInput);  // 💥 "08" becomes 0 in old browsers (octal!)

Each of these bugs could cost 3-6 hours to debug in production. Similar issues plague every language: unguarded null access, missing await, security holes from eval(), buffer overflows from strcpy(), .unwrap() panics, goroutine leaks... You’ve probably hit all of them.

---

🎯 The Solution: Your 24/7 Bug Hunting Partner

🧠 Language-Aware Meta-Runner

• ubs auto-detects JavaScript/TypeScript, Python, C/C++, Rust, Go, Java, and Ruby in the same repo and fans out to per-language scanners.
• Each scanner lives under modules/ubs-<lang>.sh, ships independently, and supports --format text|json|jsonl|sarif for consistent downstream tooling.
• Modules download lazily (PATH → repo modules/ → cached under ${XDG_DATA_HOME:-$HOME/.local/share}/ubs/modules) and are validated before execution.
• Results from every language merge into one text/JSON/SARIF report via jq, so CI systems and AI agents only have to parse a single artifact.

🔐 Supply-Chain Safeguards

• Every lazily-downloaded module ships with a pinned SHA-256 checksum baked into the meta-runner. Files fetched from GitHub are verified before they can execute, preventing tampering between releases.
• The cache lives under ${XDG_DATA_HOME:-$HOME/.local/share}/ubs/modules by default; use --module-dir to relocate it (e.g., inside a CI workspace) while retaining the same verification guarantees.
• Run ubs doctor at any time to audit your environment. It checks for curl/wget availability, writable cache directories, and per-language module integrity. Add --fix to redownload missing or corrupted modules proactively.
• Scanner runs still respect --update-modules, but an invalid checksum now causes an immediate failure with remediation guidance rather than executing unverified code.

🎛 Category Packs & Shareable Reports

• --category=resource-lifecycle focuses the scanners on Python/Go/Java resource hygiene (context managers, defer symmetry, try-with-resources). UBS automatically narrows the language set to those with lifecycle packs enabled and suppresses unrelated categories.
• --comparison=<baseline.json> diff the latest combined summary against a stored run. Deltas feed into console output, JSON, HTML, and SARIF automation metadata so CI can detect regressions.
• --report-json=<file> writes an enriched summary (project, totals, git metadata, optional comparison block) that you can archive or share with teammates/CI.
• --html-report=<file> emits a standalone HTML preview showing totals, trends vs. baseline, and per-language breakdowns—ideal for attaching to PRs or chat updates.
• All shareable outputs inject GitHub permalinks when UBS is run inside a git repo with a GitHub remote. Text output automatically annotates path:line references, JSON gains git.* metadata, and merged SARIF runs now include versionControlProvenance plus automationDetails keyed by the comparison id.

Resource lifecycle heuristics in each language

• Python – Category 16 now correlates every open() call against matching with open(...) usage and explicit encoding= parameters, while Category 19 uses the new AST helper at modules/helpers/resource_lifecycle_py.py to walk every file, socket, subprocess, asyncio task, and context cancellation path. The helper resolves alias imports, context managers, and awaited tasks so the diff counts (acquire=X, release=Y, context-managed=Z) show the exact imbalance per file.
• Go – Category 5/17 now run a Go AST walker (modules/helpers/resource_lifecycle_go.go) that detects context.With* calls missing cancel, time.NewTicker/NewTimer without Stop, os.Open/sql.Open without Close, and mutex Lock/Unlock symmetry. Findings come straight from the AST positions, so “ticker missing Stop()” lines map to the exact file:line instead of coarse regex summaries.
• Java – Category 5 surfaces FileInputStream, readers/writers, JDBC handles, etc. that were created outside try-with-resources, while Category 19 keeps tracking executor services and file streams that never close. The new summary text matches the manifest fixtures, so CI will fail if regression swallows these warnings.

Shareable output quickstart

# 1) Capture a baseline JSON (checked into CI artifacts or local history)
ubs --ci --only=python --category=resource-lifecycle \
--report-json .ubs/baseline.json test-suite/python/buggy

# 2) Re-run with comparison + HTML preview for PRs or chat threads
ubs --ci --only=python --category=resource-lifecycle \
--comparison .ubs/baseline.json \
--report-json .ubs/latest.json \
--html-report  .ubs/latest.html \
test-suite/python/buggy

latest.json now contains the git metadata (repo URL, commit, blob_base) plus a comparison.delta block, and latest.html renders a lightweight dashboard summarising the deltas. SARIF uploads also pick up the comparison id so repeating runs in CI stay grouped by automation id.

---

💡 Basic Usage

# Scan current directory
ubs .

# Scan specific directory
ubs /path/to/your/project

# Verbose mode (show more code examples)
ubs -v .

# Save report to file
ubs . bug-report.txt

# CI mode (exit code 1 on warnings)
ubs . --fail-on-warning

# Quiet mode (summary only)
ubs -q .

# Skip specific categories (e.g., skip TODO markers)
ubs . --skip=11,14

# Custom file extensions
ubs . --include-ext=js,ts,vue,svelte

Handy switches

# Git-aware quick scans (changed files only)
ubs --staged    # Scan files staged for commit
ubs --diff      # Scan working tree changes vs HEAD

# Strictness profiles
ubs --profile=strict   # Fail on warnings, enforce high standards
ubs --profile=loose    # Skip TODO/debug/code-quality nits when prototyping

# Machine-readable output
ubs . --format=json    # Pure JSON on stdout; logs go to stderr
ubs . --format=jsonl   # Line-delimited summary per scanner + totals
ubs . --format=jsonl --beads-jsonl out/findings.jsonl  # Save JSONL for Beads/"strung"

Keeping noise low

• UBS auto-ignores common junk (node_modules, virtualenvs, dist/build/target/vendor, editor caches, etc.).
• Inline suppression is available when a finding is intentional: eval("print('safe')") # ubs:ignore

🚀 Quick Install (30 Seconds)

Option 1: Automated Install (Recommended)

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash

Option 2: Integrity-first install (signed checksums)

export UBS_MINISIGN_PUBKEY="RWQg+jMrKiloMT5L3URISMoRzCMc/pVcVRCTfuY+WIzttzIr4CUJYRUk"
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/scripts/verify.sh | bash

The verifier downloads SHA256SUMS + SHA256SUMS.minisig from the matching release, validates them with minisign, checks install.sh, and only then executes it. Use --insecure to bypass verification (not recommended).

Option 3: Nix

Run directly (no install):

nix run github:Dicklesworthstone/ultimate_bug_scanner

Dev shell for contributors:

nix develop

Option 4: Docker / OCI

Pull & inspect:

docker run --rm ghcr.io/dicklesworthstone/ubs-tools ubs --help

Scan host code (risk-aware: grants container access to host FS):

docker run --rm -v /:/host ghcr.io/dicklesworthstone/ubs-tools bash -c "cd /host/path && ubs ."

⚠️ Use the host-mount pattern only when you understand the write-access implications.

Deployment & Security

• Release playbook (how we cut signed releases): docs/release.md
• Supply chain & verification model: docs/security.md

The installer will:

• ✅ Install the ubs command globally
• ✅ Optionally install ast-grep (for advanced AST analysis)
• ✅ Optionally install ripgrep (for 10x faster scanning)
• ✅ Optionally install jq (needed for JSON/SARIF merging across all language scanners)
• ✅ Optionally install typos (smart spellchecker for docs and identifiers)
• ✅ Optionally install Node.js + typescript (enables deep TypeScript type narrowing analysis)
• ✅ Auto-run ubs doctor post-install and append a session summary to ~/.config/ubs/session.md
• ✅ Capture readiness facts (ripgrep/jq/typos/type narrowing) and store them for ubs sessions --entries 1
• ✅ Set up git hooks (block commits with critical bugs)
• ✅ Set up Claude Code hooks (scan on file save)
• ✅ Add documentation to your AGENTS.md

Need to revisit what the installer discovered later? Run ubs sessions --entries 1 to view the most recent session log (or point teammates at the same summary).

Need the “just make it work” button? Run the installer with --easy-mode to auto-install every dependency, accept all prompts, detect local coding agents, and wire their quality guardrails with zero extra questions:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" \
| bash -s -- --easy-mode

Total time: 30 seconds to 2 minutes (depending on dependencies)

Need to keep your shell RC files untouched? Combine --no-path-modify (and optionally --skip-hooks) with the command above—the installer will still drop ubs into your chosen --install-dir, but it will skip both PATH edits and the alias helper entirely.

Option 2: Manual Install

# Download and install the unified runner
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs \
-o /usr/local/bin/ubs && chmod +x /usr/local/bin/ubs

# Verify it works
ubs --help

# Optional but recommended: Install dependencies
npm install -g @ast-grep/cli     # AST-based analysis
brew install ripgrep             # 10x faster searching (or: apt/dnf/cargo install)
brew install typos-cli           # Spellchecker tuned for code (or: cargo install typos-cli)
npm install -g typescript        # Enables full tsserver-based type narrowing checks

Option 3: Use Without Installing

# Download once
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs \
-o ubs && chmod +x ubs

# Run it
./ubs .

Installer Safety Nets

Uninstall from any shell

Run the installer in --uninstall mode via curl if you want to remove UBS and all of its integrations:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash -s -- --uninstall --non-interactive

This command deletes the UBS binary, shell RC snippets/aliases, config under ~/.config/ubs, and the optional Claude/Git hooks that the installer set up. Because it passes --non-interactive, it auto-confirms all prompts and runs unattended.

Flag	What it does	Why it matters
--dry-run	Prints every install action (downloads, PATH edits, hook writes, cleanup) without touching disk. Dry runs still resolve config, detect agents, and show you exactly what would change.	Audit the installer, demo it to teammates, or validate CI steps without modifying a workstation.
--self-test	Immediately runs test-suite/install/run_tests.sh after installation and exits non-zero if the smoke suite fails.	CI/CD jobs and verified setups can prove the installer still works end-to-end before trusting a release.
--skip-type-narrowing	Skip the Node.js + TypeScript readiness probe and the cross-language guard analyzers (JS/Rust/Kotlin/Swift).	Useful for air-gapped hosts or environments that want to stay in heuristic-only mode.
--skip-typos	Skip the Typos spellchecker installation + diagnostics.	Handy when corp images already provide Typos or when you deliberately disable spellcheck automation.
--skip-doctor	Skip the automatic ubs doctor run + session summary after install.	Use when CI already runs doctor separately or when you’re iterating locally and want a faster finish.

Warning

--self-test requires running install.sh from a working tree that contains test-suite/install/run_tests.sh (i.e., the repo root). Curl-piping the installer from GitHub can’t self-test because the harness isn’t present, so the flag will error out early instead of giving a false sense of safety.

Note

After every install the script now double-checks command -v ubs. If another copy shadows the freshly written binary, you’ll get an explicit warning with both paths so you can fix PATH order before running scans.

Tip

Type narrowing relies on Node.js plus the typescript npm package and the Python helpers that power the Rust/Kotlin/Swift checks. The installer now checks Node/TypeScript readiness, can optionally run npm install -g typescript, and surfaces the status inside install.sh --diagnose. Use --skip-type-narrowing if you’re on an air-gapped host or plan to keep the heuristic-only mode.

Tip

To avoid global npm permission issues, the installer now detects/installs bun just like other dependencies and uses bun install --global typescript by default, falling back to npm only if bun isn’t available.

The diagnostics also call out Swift guard readiness: if python3 is available we count .swift files under your repo and record whether the guard helper will actually run. That fact shows up in install.sh --diagnose output and the auto-generated session log so iOS/macOS teams can tell at a glance whether the ObjC-bridging heuristics are active.

Common combos

# Preview everything without touching dotfiles or hooks
bash install.sh --dry-run --no-path-modify --skip-hooks --non-interactive

# CI-friendly install that self-tests the smoke harness
bash install.sh --easy-mode --self-test --skip-hooks

🔄 Auto-Update

The ubs meta-runner automatically checks for updates once every 24 hours. If a new version is available, it self-updates securely before running your scan.

To disable this behavior (e.g., in strict environments):

export UBS_NO_AUTO_UPDATE=1
# or
ubs --no-auto-update .

Ultimate Bug Scanner is like having a senior developer review every line of code in under 5 seconds; it’s the perfect automated companion to your favorite coding agent:

$ ubs .

╔══════════════════════════════════════════════════════════════════════╗
║  🔬 ULTIMATE BUG SCANNER v4.4 - Scanning your project...             ║
╚══════════════════════════════════════════════════════════════════════╝

Project:  /Users/you/awesome-app
Files:    247 JS/TS + 58 Python + 24 Go + 16 Java + 11 Ruby + 12 C++/Rust files
Finished: 3.2 seconds

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary Statistics:
Files scanned:    247
🔥 Critical:      0    ← Would have crashed in production!
⚠️  Warnings:      8    ← Should fix before shipping
ℹ️  Info:          23   ← Code quality improvements

✨ EXCELLENT! No critical issues found ✨

---

⚡ Why Developers + AI Agents Will Love This Tool

🚀 1. Catches What Humans & AI Miss

18 specialized detection categories covering the bugs that actually matter:

Category What It Prevents Time Saved Per Bug Null Safety “Cannot read property of undefined” crashes 2-4 hours Security Holes XSS, code injection, prototype pollution 8-20 hours + reputation damage Async/Await Bugs Race conditions, unhandled rejections 4-8 hours Memory Leaks Event listeners, timers, detached DOM 6-12 hours Type Coercion JavaScript’s === vs == madness 1-3 hours + 13 more categories 100+ hours/month saved

💨 2. Blazing Fast (Because Your Time Matters)

Small project (5K lines):     0.8 seconds  ⚡
Medium project (50K lines):   3.2 seconds  🚀
Large project (200K lines):  12 seconds    💨
Huge project (1M lines):     58 seconds    🏃

That’s 10,000+ lines analyzed per second. Faster than you can say “but it worked on my machine.”

🤖 3. Built FOR AI Agents, BY Developers Who Use AI

Unlike traditional linters that fight AI-generated code, this scanner embraces it:

✅ Designed for Claude Code, Cursor, Windsurf, Aider, Continue, Copilot
✅ Zero configuration - works with ANY JS/TS, Python, C/C++, Rust, Go, Java, or Ruby project
✅ Integrates with git hooks, CI/CD, file watchers
✅ Actionable output (tells you WHAT's wrong and HOW to fix it)
✅ Fails fast in CI (catch bugs before they merge)
✅ React Hooks dependency analysis that spots missing deps, unstable objects, and stale closures
✅ Lightweight taint analysis that traces req.body/window.location/localStorage → innerHTML/res.send/eval/exec/db.query and flags flows without DOMPurify/escapeHtml/parameterized SQL

📊 4. Real-World Impact

Scenario	Without Scanner	With Scanner
AI implements user auth	• 3 null pointer crashes (9h debugging) • 1 XSS vulnerability (8h + incident) • 2 race conditions (4h debugging) Total: ~21 hours + security incident	• All issues caught in 4 seconds • Fixed before commit (15 min) Total: 15 minutes Savings: 84x faster ⚡
Refactor payment flow	• Division by zero in edge case (3h) • Unhandled promise rejection (2h) • Missing error logging (1h) Total: 6 hours debugging	• Caught instantly (3 sec) • Fixed before merge (10 min) Total: 10 minutes Savings: 36x faster 🚀

---

🤖 AI Agent Integration (The Real Magic)

On-Device Agent Guardrails

install.sh now inspects your workstation for the most common coding agents (the same set listed below) and, when asked, drops guardrails that remind those agents to run ubs --fail-on-warning . before claiming a task is done. In --easy-mode this happens automatically; otherwise you can approve each integration individually.

Agent / IDE	What we wire up	Why it helps
Claude Code Desktop (.claude/hooks/on-file-write.sh)	File-save hook that shells out to ubs --ci whenever Claude saves JS/TS files.	Keeps Claude from accepting “Apply Patch” without a fresh scan.
Cursor (.cursor/rules)	Shared rule block that tells Cursor plans/tasks to run ubs --fail-on-warning . and summarize outstanding issues.	Cursor’s autonomous jobs inherit the same QA checklist as humans.
Codex CLI (.codex/rules)	Adds the identical rule block for Anthropic’s Codex terminal workflow.	Ensures Codex sessions never skip the scanner during long refactors.
Gemini Code Assist (.gemini/rules)	Guidance instructing Gemini agents to run ubs before closing a ticket.	Keeps Gemini’s asynchronous fixes aligned with UBS exit criteria.
Windsurf (.windsurf/rules)	Guardrail text + sample command palette snippet referencing ubs.	Windsurf’s multi-step plans stay grounded in the same quality gate.
Cline (.cline/rules)	Markdown instructions that Cline’s VS Code extension ingests.	Forces every “tool call” from Cline to mention scanner findings.
OpenCode MCP (.opencode/rules)	Local MCP instructions so HTTP tooling always calls ubs before replying.	Makes OpenCode’s multi-agent swarms share the same notion of “done”.

Why This Matters for AI Workflows

When you’re coding with AI, you’re moving 10-100x faster than traditional development. But bugs accumulate just as quickly. Traditional tools slow you down. This scanner keeps pace:

Traditional workflow:              AI-powered workflow with scanner:
┌──────────────────┐              ┌──────────────────┐
│ AI writes code   │              │ AI writes code   │
└────────┬─────────┘              └────────┬─────────┘
│                                 │
↓                                 ↓
┌──────────────────┐              ┌──────────────────┐
│ You review       │              │ Scanner runs     │
│ (15 min)         │              │ (3 seconds)      │
└────────┬─────────┘              └────────┬─────────┘
│                                 │
↓                                 ↓
┌──────────────────┐              ┌──────────────────┐
│ Tests pass?      │              │ Critical bugs?   │
└────────┬─────────┘              └────────┬─────────┘
│ NO!                              │ YES!
↓                                 ↓
┌──────────────────┐              ┌──────────────────┐
│ Debug in prod    │              │ AI fixes them    │
│ (6 hours)        │              │ (5 minutes)      │
└──────────────────┘              └────────┬─────────┘
↓
┌──────────────────┐
│ Ship with         │
│ confidence        │
└──────────────────┘

Total: 6.25 hours                Total: 8 minutes

Pattern 1: Claude Code Integration (Real-Time Scanning)

Drop this into .claude/hooks/on-file-write.sh:

#!/bin/bash
# Auto-scan UBS-supported languages (JS/TS, Python, C/C++, Rust, Go, Java, Ruby) on save

if [[ "$FILE_PATH" =~ \.(js|jsx|ts|tsx|mjs|cjs|py|pyw|pyi|c|cc|cpp|cxx|h|hh|hpp|hxx|rs|go|java|rb)$ ]]; then
echo "🔬 Quality check running..."

if ubs "${PROJECT_DIR}" --ci 2>&1 | head -30; then
echo "✅ No critical issues"
else
echo "⚠️  Issues detected - review above"
fi
fi

Result: Every time Claude writes code, the scanner catches bugs instantly.

Pattern 2: Git Pre-Commit Hook (Quality Gate)

The installer can set this up automatically, or add to .git/hooks/pre-commit:

#!/bin/bash
# Block commits with critical bugs

echo "🔬 Running bug scanner..."

if ! ubs . --fail-on-warning 2>&1 | tee /tmp/scan.txt | tail -30; then
echo ""
echo "❌ Critical issues found. Fix them or use: git commit --no-verify"
echo ""
echo "Top issues:"
grep -A 3 "🔥 CRITICAL" /tmp/scan.txt | head -20
exit 1
fi

echo "✅ Quality check passed - committing..."

Result: Bugs cannot be committed. Period.

Pattern 3: Cursor/Windsurf/Continue Integration

Add to your .cursorrules or similar:

## Code Quality Standards

Before marking any task as complete:

1. Run the bug scanner: `ubs .`
2. Fix ALL critical issues (🔥)
3. Review warnings (⚠️) and fix if trivial
4. Only then mark task complete

If the scanner finds critical issues, your task is NOT done.

Result: AI agents have built-in quality standards.

Pattern 4: CI/CD Pipeline (GitHub Actions Example)

name: Code Quality Gate

on: [push, pull_request]

jobs:
bug-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

- name: Install Bug Scanner
run: |
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash -s -- --non-interactive

- name: Scan for Bugs
run: |
ubs . --fail-on-warning --ci

Result: Pull requests with critical bugs cannot merge.

Pattern 5: The Fix-Verify Loop (For AI Agents)

This is the golden pattern for AI coding workflows:

#!/bin/bash
# Have your AI agent run this after implementing features

echo "🔬 Post-implementation quality check..."

# Run scanner
if ubs . --fail-on-warning > /tmp/scan-result.txt 2>&1; then
echo "✅ All quality checks passed!"
echo "📝 Ready to commit"
exit 0
else
echo "❌ Issues found:"
echo ""

# Show critical issues
grep -A 5 "🔥 CRITICAL" /tmp/scan-result.txt | head -30

echo ""
echo "🤖 AI: Please fix these issues and re-run this check"
exit 1
fi

Usage pattern:

User: "Add user registration with email validation"

AI Agent:
1. Implements the feature
2. Runs quality check (scanner finds 3 critical bugs)
3. Fixes the bugs
4. Re-runs quality check (passes)
5. Commits the code

Total time: 12 minutes (vs. 6 hours debugging in production)

Pattern 6: The “AI Agent Decision Tree”

Train your AI agent to use this decision tree:

Did I modify code in any supported language?
(JS/TS, Python, Go, Rust, Java, C++, Ruby)
│
↓ YES
Changed more than 50 lines?
│
↓ YES
Run scanner ←──────────┐
│                 │
↓                 │
Critical issues found? ────┤ YES
│ NO              │
↓                 │
Warnings?             │
│                 │
↓ YES             │
Show to user             │
Ask if should fix ───────┤
│ NO              │
↓                 ↓
Commit code      Fix issues

---

Important

Copy the blurb below to your project’s AGENTS.md, .claude/claude_docs/, or .cursorrules file for comprehensive UBS integration guidance.

## UBS Quick Reference for AI Agents

UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**

**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/main/install.sh | bash`

**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.

**Commands:**
```bash
ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
ubs $(git diff --name-only --cached)    # Staged files — before commit
ubs --only=js,python src/               # Language filter (3-5x faster)
ubs --ci --fail-on-warning .            # CI mode — before PR
ubs --help                              # Full command reference
ubs sessions --entries 1                # Tail the latest install session log
ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)

Output Format:

⚠️  Category (N errors)
file.ts:42:5 – Issue description
💡 Suggested fix
Exit code: 1

Parse: file:line:col → location | 💡 → how to fix | Exit 0/1 → pass/fail

Fix Workflow:

1. Read finding → category + fix suggestion
2. Navigate file:line:col → view context
3. Verify real issue (not false positive)
4. Fix root cause (not symptom)
5. Re-run ubs <file> → exit 0
6. Commit

Speed Critical: Scope to changed files. ubs src/file.ts (< 1s) vs ubs . (30s). Never full scan for small edits.

Bug Severity:

• Critical (always fix): Null safety, XSS/injection, async/await, memory leaks
• Important (production): Type narrowing, division-by-zero, resource leaks
• Contextual (judgment): TODO/FIXME, console logs

Anti-Patterns:

• ❌ Ignore findings → ✅ Investigate each
• ❌ Full scan per edit → ✅ Scope to file
• ❌ Fix symptom (if (x) { x.y }) → ✅ Root cause (x?.y)

---

## 🎬 **See It In Action**

*Examples show JavaScript output; each language has equivalent detections \(Python: None checks, Go: nil guards, Rust: Option handling, etc\.\)*

### **Example 1: Catching a Null Pointer Bug**

$ ubs src/

▓▓▓ NULL SAFETY & DEFENSIVE PROGRAMMING Detects: Null pointer dereferences, missing guards, unsafe property access

🔥 CRITICAL (5 found) Unguarded property access after getElementById Consider: const el = document.getElementById(‘x’); if (!el) return;

src/components/form.js:42 const submitBtn = document.getElementById(‘submit-button’); submitBtn.classList.add(‘active’); // ← Crashes if element missing

src/utils/dom.js:87 const modal = document.querySelector(‘.modal’); modal.style.display = ‘block’; // ← Runtime crash guaranteed

💡 Fix: Always check for null before accessing properties

**Before:** 3 production crashes this week **After:** 0 crashes, caught in 2 seconds

### **Example 2: Security Vulnerability Detection**

▓▓▓ ASYNC/AWAIT & PROMISE PITFALLS Detects: Missing await, unhandled rejections, race conditions

🔥 CRITICAL (8 found) await used in non-async function SyntaxError in JavaScript

src/api/users.js:67 function saveUser(data) { await database.insert(data); // ← SyntaxError! }

⚠️ WARNING (12 found) Promises without .catch() or try/catch Unhandled rejections crash Node.js

src/services/email.js:45 sendEmail(user.email).then(result => …) // ← No error handling!

**Before:** Silent failures, mysterious bugs in production **After:** All async bugs caught and fixed before deploy

---

## 📋 **What It Detects \(The Complete Arsenal\)**

*Each language module has specialized detections\. Examples below are representative \(JavaScript shown; Python has `eval()`, Go has goroutine leaks, Rust has `.unwrap()` panics, C\+\+ has buffer overflows, etc\.\)*

### 🔴 **Critical Issues \(Production Blockers\)**

These **WILL** cause crashes, security breaches, or data corruption:


| Pattern | Example | Why It's Dangerous |
| ------- | ------- | ------------------ |
| `eval()` usage | `eval(userInput)` | Allows arbitrary code execution - **RCE vulnerability** |
| Direct NaN comparison | `if (x === NaN)` | Always returns false - **logic bug** |
| Missing await | `asyncFunc()` in async context | Silent failures, race conditions - **data corruption** |
| Prototype pollution | `obj.__proto__ = {}` | Security vulnerability - **privilege escalation** |
| Unguarded null access | `el.style.color` without null check | **Runtime crash** guaranteed |
| `parseInt` without radix | `parseInt("08")` | Returns 0 in some browsers - **calculation bug** |
| Empty catch blocks | `catch(e) {}` | Swallows errors - **debugging nightmare** |
| `innerHTML` with user data | `el.innerHTML = userInput` | **XSS vulnerability** |
| Missing async keyword | `await` without `async function` | **SyntaxError** |
| Hardcoded secrets | `const key = "sk_live..."` | **Security breach** |

### 🟡 **Warnings \(Should Fix Before Shipping\)**

These cause bugs, performance issues, or maintenance headaches:


| Pattern | Example | Impact |
| ------- | ------- | ------ |
| Promises without `.catch()` | `promise.then(...)` | Unhandled rejections crash Node\.js |
| Division without zero check | `total / count` | Returns `Infinity` or `NaN` |
| Event listeners without cleanup | `addEventListener` in React | **Memory leak** \(app gets slower over time\) |
| `setInterval` without clear | `setInterval(fn, 1000)` | **Timer leak** \(infinite timers\) |
| `await` inside loops | `for(...) { await api.call() }` | **Slow** \(sequential, not parallel\) |
| Array mutation during iteration | `arr.forEach(() => arr.push(...))` | **Skipped/duplicate** elements |
| Missing switch default | `switch(x) { case 1: ... }` | Unhandled values cause silent failures |
| `isNaN()` instead of `Number.isNaN()` | `isNaN("foo")` | Type coercion bugs |

### 🔵 **Info \(Code Quality & Best Practices\)**

Improvements that make code cleaner and more maintainable:

- Optional chaining opportunities \(`obj?.prop?.value`\)
- Nullish coalescing opportunities \(`value ?? default`\)
- TypeScript `any` usage \(reduces type safety\)
- `console.log` statements \(remove before production\)
- Technical debt markers \(TODO, FIXME, HACK\)
- Performance optimizations \(DOM queries in loops\)
- `var` usage \(use `let`/`const` instead\)
- Deep property access without guards
- Large inline arrays \(move to separate files\)
- Complex nested ternaries \(readability\)

---

## ⚙️ **Advanced Configuration**

### **Command-Line Options \(Full Reference\)**

ubs [OPTIONS] [PROJECT_DIR] [OUTPUT_FILE]

Core Options: -v, –verbose Show 10 code samples per finding (default: 3) -q, –quiet Minimal output (summary only) –ci CI mode (stable output, no colors by default) –fail-on-warning Exit with code 1 on warnings (strict mode) –version Print UBS meta-runner version and exit –profile=MODE strict|loose (sets defaults for strictness) –baseline=FILE Compare findings against a baseline JSON (alias for –comparison) -h, –help Show help and exit

Git Integration: –staged Scan only files staged for commit –diff, –git-diff Scan only modified files (working tree vs HEAD)

Output Control: –format=FMT Output format: text|json|jsonl|sarif (default: text) –beads-jsonl=FILE Write JSONL summary alongside normal output for Beads/“strung” –no-color Force disable ANSI colors OUTPUT_FILE Save report to file (auto-tees to stdout)

File Selection: –include-ext=CSV File extensions (default: auto-detect by language) JS: js,jsx,ts,tsx,mjs,cjs | Python: py,pyi,pyx Go: go | Rust: rs | Java: java | C++: cpp,cc,cxx,c,h Ruby: rb,rake,ru | Custom: –include-ext=js,ts,vue –exclude=GLOB[,…] Additional paths to exclude (comma-separated) Example: –exclude=legacy (deps ignored by default)

Performance: –jobs=N Parallel jobs for ripgrep (default: auto-detect cores) Set to 1 for deterministic output

Rule Control: –skip=CSV Skip categories by number (see output for numbers) Example: –skip=11,14 # Skip debug code + TODOs –skip-type-narrowing Disable tsserver-based guard analysis (falls back to text heuristics) –rules=DIR Additional ast-grep rules directory Rules are merged with built-in rules –no-auto-update Disable automatic self-update –suggest-ignore Print large-directory candidates to add to .ubsignore (no changes applied)

Environment Variables: JOBS Same as –jobs=N NO_COLOR Disable colors (respects standard) CI Enable CI mode automatically

Arguments: PROJECT_DIR Directory to scan (default: current directory) OUTPUT_FILE Save full report to file

Exit Codes: 0 No critical issues (or no issues at all) 1 Critical issues found 1 Warnings found (only with –fail-on-warning) 2 Invalid arguments or configuration

### **Examples**

Basic scan

ubs .

Verbose scan with full details

ubs -v /path/to/project

Strict mode for CI (fail on any warning)

ubs –fail-on-warning –ci

Save report without cluttering terminal

ubs . report.txt

Scan Vue.js project

ubs . –include-ext=js,ts,vue

Skip categories you don’t care about

ubs . –skip=14 # Skip TODO/FIXME markers

Maximum performance (use all cores)

ubs –jobs=0 . # Auto-detect ubs –jobs=16 . # Explicit core count

Exclude vendor code

ubs . –exclude=node_modules,vendor,dist,build

Custom rules directory

ubs . –rules=~/.config/ubs/custom-rules

Combine multiple options

ubs -v –fail-on-warning –exclude=legacy –include-ext=js,ts,tsx . report.txt

### JSONL schema

`--format=jsonl` \(and `--beads-jsonl=FILE`\) emit newline-delimited objects for easy piping into tools like Beads or `jq`:

{“type”:“scanner”,“project”:“/path/to/project”,“language”:“python”,“files”:42,“critical”:1,“warning”:3,“info”:12,“timestamp”:“2025-11-22T09:04:20Z”} {“type”:“totals”,“project”:“/path/to/project”,“files”:99,“critical”:1,“warning”:3,“info”:27,“timestamp”:“2025-11-22T09:04:22Z”}

### **Custom AST-Grep Rules**

You can add your own bug detection patterns:

Create custom rules directory

mkdir -p ~/.config/ubs/rules

Add a custom rule (YAML format)

cat > ~/.config/ubs/rules/no-console-in-prod.yml <<‘EOF’ id: custom.no-console-in-prod language: javascript rule: any:

• pattern: console.log($$$)
• pattern: console.debug($$$)
• pattern: console.info($$$) severity: warning message: “console statements should be removed before production” note: “Use a proper logging library or remove debug statements” EOF

Run with custom rules

ubs . –rules=~/.config/ubs/rules

**Common custom rules:**

Enforce specific naming conventions

id: custom.component-naming language: typescript rule: pattern: export function $NAME() { $$$ } not: pattern: export function $UPPER() { $$$ } severity: info message: “React components should start with uppercase letter”

Catch specific anti-patterns in your codebase

id: custom.no-direct-state-mutation language: typescript rule: pattern: this.state.$FIELD = $VALUE severity: critical message: “Never mutate state directly - use setState()”

### **Excluding False Positives**

If the scanner reports false positives for your specific use case:

Skip entire categories

ubs . –skip=11,14 # Skip debug code detection and TODO markers

Exclude specific files/directories

ubs . –exclude=legacy,third-party,generated

For persistent config, create a wrapper script

cat > _{/bin/ubs-custom <<‘EOF’ #!/bin/bash ubs “$@”
–exclude=legacy,generated
–skip=14
–rules=}/.config/ubs/rules EOF chmod +x ~/bin/ubs-custom

---

## 🎓 **How It Works \(Under the Hood\)**

### **Multi-Layer Analysis Engine**

The scanner uses a sophisticated 4-layer approach:

Layer 1: PATTERN MATCHING (Fast) ──┐ ├─ Regex-based detection │ ├─ Optimized with ripgrep │ └─ Finds 70% of bugs in <1 second │ ├──► Combined Results Layer 2: AST ANALYSIS (Deep) ──────┤ ├─ Semantic code understanding │ ├─ Powered by ast-grep │ └─ Catches complex patterns │ │ Layer 3: CONTEXT AWARENESS (Smart) ┤ ├─ Understands surrounding code │ ├─ Reduces false positives │ └─ Knows when rules don’t apply │ │ Layer 4: STATISTICAL (Insightful) │ ├─ Code smell detection │ ├─ Anomaly identification │ └─ Architectural suggestions │ ↓ Final Report (3-5 sec)

### **Technology Stack**


| Component | Technology | Purpose | Why This Choice |
| --------- | ---------- | ------- | --------------- |
| **Core Engine** | Bash 4\.0\+ | Orchestration | Universal compatibility, zero dependencies |
| **Pattern Matching** | Ripgrep | Text search | 10-100x faster than grep, parallelized |
| **AST Parser** | ast-grep | Semantic analysis | Understands code structure, not just text |
| **Fallback** | GNU grep | Text search | Works on any Unix-like system |
| **Rule Engine** | YAML | Pattern definitions | Human-readable, easy to extend |

### **Performance Optimizations**

Automatic parallelization (uses all CPU cores)

• Auto-detects: 16-core = 16 parallel jobs
• Manually set: –jobs=N

Smart file filtering (only scans relevant files)

• JS/TS: .js, .jsx, .ts, .tsx, .mjs, .cjs (auto-skip node_modules/dist/build)
• Python: .py + pyproject/requirements (skip venv/pycache)
• C/C++: .c/.cc/.cpp/.cxx + headers + CMake files (skip build/out)
• Rust: .rs + Cargo manifests (skip target/.cargo)
• Go: .go + go.mod/go.sum/go.work (skip vendor/bin)
• Java: .java + pom.xml + Gradle scripts (skip target/build/out)
• Ruby: .rb + Gemfile/Gemspec/Rakefile (skip vendor/bundle,tmp)
• Custom: –include-ext=js,ts,vue

Efficient streaming (low memory usage)

• No temp files created
• Results streamed as found
• Memory usage: <100MB for most projects

Incremental scanning (future feature)

• Only scan changed files (git diff)
• Cache previous results
• 10x faster on large projects

---

## 🏆 **Comparison with Other Tools**


| Feature | Ultimate Bug Scanner | ESLint | TypeScript | SonarQube | DeepCode |
| ------- | -------------------- | ------ | ---------- | --------- | -------- |
| **Setup Time** | 30 seconds | 30 minutes | 1-2 hours | 2-4 hours | Account required |
| **Speed \(50K lines\)** | 3 seconds | 15 seconds | 8 seconds | 2 minutes | Cloud upload |
| **Zero Config** | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
| **Works Without Types** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |
| **Null Safety** | ✅ Yes | ⚠️ Limited | ✅ Yes | ⚠️ Limited | ⚠️ Limited |
| **Security Scanning** | ✅ Yes | ⚠️ Plugin | ❌ No | ✅ Yes | ✅ Yes |
| **Memory Leaks** | ✅ Yes | ❌ No | ❌ No | ⚠️ Limited | ❌ No |
| **Async/Await** | ✅ Deep | ⚠️ Basic | ✅ Good | ⚠️ Basic | ⚠️ Basic |
| **CI/CD Ready** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ Cloud |
| **Offline** | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ Limited | ❌ No |
| **AI Agent Friendly** | ✅ Built for it | ⚠️ Config heavy | ⚠️ Config heavy | ❌ Complex | ⚠️ Cloud |
| **Cost** | Free | Free | Free | $$$$ | $$$ |

**When to use what:**

- **Ultimate Bug Scanner**: Quick scans, AI workflows, no config needed
- **ESLint**: Style enforcement, custom rules, team standards
- **TypeScript**: Type safety \(use WITH this scanner\)
- **SonarQube**: Enterprise compliance, detailed metrics
- **DeepCode**: ML-powered analysis \(if you trust cloud\)

**Best combo:** TypeScript \+ ESLint \+ Ultimate Bug Scanner = Maximum safety

---

## 🧠 **Project Justification and Rationale**

### **Why This Exists \(And Why It's Not "Just Another Linter"\)**

You might be thinking: *"We already have ESLint, Pylint, Clippy, RuboCop\.\.\. why build another tool?"*

**Fair question\. And honestly, your first reaction is probably right to be skeptical\.**

### **The Initial Skepticism is Valid \(But Misses the Point\)**

When you first look at UBS, it's natural to think:

> *"This is just worse ESLint\. It has fewer rules, uses regex \(false positives\!\), and doesn't auto-fix anything\. Why would I use this instead of mature, comprehensive linters?"*

**That's analyzing through the wrong lens\.**

You're comparing it to tools designed for a **fundamentally different workflow** \(human developers writing code manually\) when it's solving a **fundamentally different problem** \(LLM agents generating code at 100x speed\)\.

It's like comparing a smoke detector to a building inspector:

- **Building inspector \(ESLint\):** Thorough, comprehensive, finds every issue, takes hours
- **Smoke detector \(UBS\):** Fast, catches critical dangers, instant alert, always running

**You need both\.** But when your house might be on fire \(AI just generated 500 lines in 30 seconds\), you want the smoke detector first\.

### **The Paradigm Shift: AI-Native Development**

Software development is undergoing a **fundamental transformation**:

**2020 \(Pre-LLM Era\):**

- Developer writes 50-200 lines/day manually
- Deep thought before each line
- Single language per project \(mostly\)
- Time to review: abundant
- Quality gate: comprehensive linting \+ code review \(hours\)

**2025 \(LLM Era\):**

- AI generates 500-5000 lines/day across projects
- Code appears in seconds
- Polyglot projects standard \(microservices in Go, UI in TypeScript, ML in Python, workers in Rust\)
- Time to review: scarce
- Quality gate needed: instant feedback \(\<5s\) or the loop breaks

**Traditional tools weren't designed for this\.** They were built when "code generation" meant 200 lines/day, not 2000\.

### **Here's the Fundamental Difference:**

### **1\. This Tool is Built FOR AI Agents, Not Just Humans**

Traditional linters were designed for **human developers** in **single-language codebases**\. UBS is designed for **LLM coding agents** working across **polyglot projects**\.

**The paradigm shift:**


| Traditional Linting \(Human-First\) | UBS Approach \(LLM-First\) |
| ----------------------------------- | -------------------------- |
| **Goal:** Comprehensive coverage \+ auto-fix  <br>**Speed:** 15-60 seconds acceptable  <br>**Setup:** 30 min config per language  <br>**Languages:** One tool per language  <br>**False positives:** Must be \<1% \(frustrates humans\)  <br>**Output:** Human-readable prose | **Goal:** Critical bug detection \+ fast feedback  <br>**Speed:** \<5 seconds required  <br>**Setup:** Zero config \(instant start\)  <br>**Languages:** One scan for all 7 languages  <br>**False positives:** 10-20% OK \(LLMs filter instantly\)  <br>**Output:** Structured file:line for LLM parsing |

### **2\. LLMs Don't Need Auto-Fix—They ARE the Auto-Fix Engine**

**Why traditional linters have auto-fix:**

// ESLint flags: “Use === instead of ==” if (value == null) // ❌

// ESLint auto-fix (rigid, no context): if (value === null) // ✅ Technically correct, but…

**Why UBS doesn't \(and shouldn't\):**

// UBS flags: “Type coercion bug: == should be ===” if (value == null) // ❌

// Claude reads the error and understands context: if (value !== null && value !== undefined) // ✅ Better - handles both // OR if (value != null) // ✅ Or keeps == for null/undefined (intentional)

**The hard part is DETECTION, not fixing\.** Once flagged, LLMs can:

- Understand semantic context
- Consider surrounding code
- Apply the right fix \(not just the mechanical one\)
- Refactor holistically

Auto-fix would be **worse** because it's context-free\. LLMs need to know **WHAT'S wrong** and **WHERE**, then they fix it properly\.

### **3\. The Multi-Language Zero-Config Design is the Moat**

**Imagine asking Claude to set up quality gates for a polyglot project:**

**Traditional approach \(15-30 min per project\):**

JavaScript/TypeScript

npm install –save-dev eslint @eslint/js @typescript-eslint/parser

Create .eslintrc.js (200 lines of config)

Python

pip install pylint black mypy

Create .pylintrc, pyproject.toml sections

Rust

Add to Cargo.toml: [lints]

Configure clippy rules

Go

Install golangci-lint, create .golangci.yml

Java

Setup Checkstyle + PMD + SpotBugs + config XMLs

C++

Setup clang-tidy, create .clang-tidy config

Ruby

Create .rubocop.yml with 150+ lines

Now run 7 different commands and parse 7 different output formats…

**UBS approach \(30 seconds\):**

curl -fsSL https://raw.githubusercontent.com/…/install.sh | bash ubs .

Done. All 7 languages scanned, unified report.

**This matters because:**

- LLMs generate code across languages in one session \(Python API → Go service → TypeScript UI → Rust worker\)
- Configuring 7 tools is error-prone for LLMs
- Humans don't want to maintain 7 different config files
- CI/CD pipelines want one command, one exit code

### **Type Narrowing Coverage Across Languages**

- **TypeScript** – UBS shells out to `tsserver` \(via the bundled helper\) whenever Node\.js \+ the `typescript` package are available\. The installer surfaces a "Type narrowing readiness" diagnostic so you immedi