ubs

Q: How do I install ubs?

Run npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill ubs in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ubs/ (personal) or .claude/skills/ubs/ (project).

by dicklesworthstoneCode Quality & Workflow

Ultimate Bug Scanner - Pre-commit static analysis for AI coding workflows. 18 detection categories, 8 languages, 4-layer analysis engine. The AI agent's quality gate.

Installs: 64
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill ubs

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads ubs automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

UBS - Ultimate Bug Scanner

Static analysis tool built for AI coding workflows. Catches bugs that AI agents commonly introduce: null safety, async/await issues, security holes, memory leaks. Scans JS/TS, Python, Go, Rust, Java, C++, Ruby, Swift in 3-5 seconds.

Why This Exists

AI agents move fast. Bugs move faster. You're shipping features in minutes, but:

Null pointer crashes slip through
Missing await causes silent failures
XSS vulnerabilities reach production
Memory leaks accumulate

UBS is the quality gate: scan before commit, fix before merge.

Golden Rule

ubs <changed-files> --fail-on-warning

Exit 0 = safe to commit. Exit 1 = fix and re-run.

Essential Commands

Quick Scans (Use These)

ubs file.ts file2.py                    # Specific files (< 1s)
ubs $(git diff --name-only --cached)    # Staged files
ubs --staged                            # Same, cleaner syntax
ubs --diff                              # Working tree vs HEAD

Full Project Scans

ubs .                                   # Current directory
ubs /path/to/project                    # Specific path
ubs --only=js,python src/               # Language filter (faster)

CI/CD Mode

ubs --ci --fail-on-warning .            # Strict mode for CI
ubs --format=json .                     # Machine-readable
ubs --format=sarif .                    # GitHub code scanning

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

The 18 Detection Categories

Critical (Always Fix)

Category	What It Catches
Null Safety	Unguarded property access, missing null checks
Security	XSS, injection, prototype pollution, hardcoded secrets
Async/Await	Missing await, unhandled rejections, race conditions
Memory Leaks	Event listeners without cleanup, timer leaks
Type Coercion	`==` vs `===`, `parseInt` without radix, NaN comparison

Important (Production Risk)

Category	What It Catches
Division Safety	Division without zero check
Resource Lifecycle	Unclosed files, connections, context managers
Error Handling	Empty catch blocks, swallowed errors
Promise Chains	`.then()` without `.catch()`
Array Mutations	Mutating during iteration

Code Quality (Contextual)

Category	What It Catches
Debug Code	`console.log`, `debugger`, `print()` statements
TODO Markers	`TODO`, `FIXME`, `HACK` comments
Type Safety	TypeScript `any` usage
Readability	Complex ternaries, deep nesting

Language-Specific Detection

Language	Key Patterns
JavaScript/TypeScript	innerHTML XSS, eval(), missing await, React hooks deps
Python	eval(), open() without with, missing encoding=, None checks
Go	Nil pointer, goroutine leaks, defer symmetry, context cancel
Rust	`.unwrap()` panics, `unsafe` blocks, Option handling
Java	Resource leaks (try-with-resources), null checks, JDBC
C/C++	Buffer overflows, strcpy(), memory leaks, use-after-free
Ruby	eval(), send(), instance_variable_set
Swift	Force unwrap (!), ObjC bridging issues

Profiles

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

Category Packs (Focused Scans)

ubs --category=resource-lifecycle .    # Python/Go/Java resource hygiene

Narrows scan to relevant languages and suppresses unrelated categories.

Comparison Mode (Regression Detection)

# Capture baseline
ubs --ci --report-json .ubs/baseline.json .

# Compare against baseline
ubs --ci --comparison .ubs/baseline.json --report-json .ubs/latest.json .

Useful for CI to detect regressions vs. main branch.

Output Formats

Format	Flag	Use Case
text	(default)	Human-readable terminal output
json	`--format=json`	Machine parsing, scripting
jsonl	`--format=jsonl`	Line-delimited, streaming
sarif	`--format=sarif`	GitHub code scanning
html	`--html-report=file.html`	PR attachments, dashboards

Inline Suppression

When a finding is intentional:

eval(trustedCode);  // ubs:ignore

// ubs:ignore-next-line
dangerousOperation();

Exit Codes

Code	Meaning
`0`	No critical issues (safe to commit)
`1`	Critical issues or warnings (with `--fail-on-warning`)
`2`	Environment error (missing ast-grep, etc.)

Doctor Command

ubs doctor                # Check environment
ubs doctor --fix          # Auto-fix missing dependencies

Checks: curl/wget, ast-grep, ripgrep, jq, typos, Node.js + TypeScript.

Agent Integration

UBS auto-configures hooks for coding agents during install:

Agent	Hook Location
Claude Code	`.claude/hooks/on-file-write.sh`
Cursor	`.cursor/rules`
Codex CLI	`.codex/rules/ubs.md`
Gemini	`.gemini/rules`
Windsurf	`.windsurf/rules`
Cline	`.cline/rules`

Claude Code Hook Pattern

#!/bin/bash
# .claude/hooks/on-file-write.sh
if [[ "$FILE_PATH" =~ \.(js|jsx|ts|tsx|py|go|rs|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

Git Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit
echo "🔬 Running bug scanner..."
if ! ubs . --fail-on-warning 2>&1 | tail -30; then
  echo "❌ Critical issues found. Fix or: git commit --no-verify"
  exit 1
fi
echo "✅ Quality check passed"

Performance

Small (5K lines):     0.8 seconds
Medium (50K lines):   3.2 seconds
Large (200K lines):   12 seconds
Huge (1M lines):      58 seconds

10,000+ lines per second. Use --jobs=N to control parallelism.

Speed Tips

Scope to changed files: ubs src/file.ts (< 1s) vs ubs . (30s)
Use --staged or --diff: Only scan what you're committing
Language filter: --only=js,python skips irrelevant scanners
Skip categories: --skip=11,14 to skip debug/TODO markers

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

Bug Severity Guide

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

Common Anti-Patterns

Don't	Do
Ignore findings	Investigate each
Full scan per edit	Scope to changed files
Fix symptom (`if (x) { x.y }`)	Fix root cause (`x?.y`)
Suppress without understanding	Verify false positive first

Installation

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

# Manual
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/ubs \
  -o /usr/local/bin/ubs && chmod +x /usr/local/bin/ubs

Custom AST Rules

mkdir -p ~/.config/ubs/rules

cat > ~/.config/ubs/rules/no-console.yml <<'EOF'
id: custom.no-console
language: javascript
rule:
  pattern: console.log($$$)
severity: warning
message: "Remove console.log before production"
EOF

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

Excluding Paths

ubs . --exclude=legacy,generated,vendor

Auto-ignored: node_modules, .venv, dist, build, target, editor caches.

Session Logs

ubs sessions --entries 1    # View latest install session

Integration with Flywheel

Tool	Integration
BV	`--beads-jsonl=out.jsonl` exports findings for Beads
CASS	Search past sessions for similar bug patterns
CM	Extract rules from UBS findings
Agent Mail	Notify agents of scan results
DCG	UBS runs inside DCG protection

Troubleshooting

Error	Fix
"Environment error" (exit 2)	`ubs doctor --fix`
"ast-grep not found"	`brew install ast-grep` or `cargo install ast-grep`
Too many false positives	Use `--skip=N` or `// ubs:ignore`
Slow scans	Scope to files: `ubs <file>` not `ubs .`

FAQ

What does the ubs skill do?

Ultimate Bug Scanner - Pre-commit static analysis for AI coding workflows. 18 detection categories, 8 languages, 4-layer analysis engine. The AI agent's quality gate.

How do I install ubs?

Run npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill ubs in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ubs/ (personal) or .claude/skills/ubs/ (project).

Which AI agents can use ubs?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is ubs safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains ubs?

It is published by dicklesworthstone in dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations. It has 64 recorded installs.