Autonomous AI-powered code quality tool that finds and fixes production issues while you sleep

Star this repo if you find it useful!

npm install
npm run qa-ralph
# Dashboard opens at localhost:3000 - watch it work!

• Catch bugs before production - Find hardcoded values, debug code, and secrets before they ship
• Save hours of manual review - Let AI handle repetitive code quality checks
• Works with any codebase - JavaScript, TypeScript, React, Next.js, Node.js, and more
• Real results - "Fixed 142 issues overnight for $4.30"

• Node.js 18+ - Download
• Claude Code CLI - VS Code extension or standalone

# 1. Clone the repository
git clone https://github.com/JamesMo14/Ralph-Mode.git
cd Ralph-Mode

# 2. Install dependencies
npm install

# 3. Run for first time (generates .qawatch.json config)
npm run qa-watch

# 4. Customize config if needed
# Edit .qawatch.json to match your project structure

Claude Code CLI is required for QA Watcher to work. Install it via:

1. VS Code Extension (recommended): Install "Claude Code" from VS Code marketplace
2. Standalone: Download from claude.ai/download

The CLI path is auto-detected on first run. If needed, update the path in .qawatch.json.

Monitor file changes in real-time. Issues are detected but not auto-fixed.

npm run qa-watch

Best for: Active development, learning what issues exist

Automatically fix safe patterns when issues are detected.

npm run qa-watch:fix
# or
npm run qa-watch -- --fix

Best for: Quick cleanup while coding

Autonomous cleanup mode. Scans your entire codebase and fixes issues in a loop until clean or budget is reached.

npm run qa-ralph

Best for: Overnight cleanup, initial codebase scan, CI/CD integration

Ralph Mode features:

• Live dashboard at localhost:3000
• Automatic retry on failures
• Budget controls ($5 warning, $20 hard stop by default)
• Progress tracking with issue counts

QA Watcher uses .qawatch.json in your project root. A default config is generated on first run.

{
  "watchPaths": ["./src", "./app", "./components"],
  "ralph": {
    "maxCycles": 10,
    "budgetHard": 20.00
  }
}

{
  "watchPaths": ["./src", "./app", "./components", "./lib"],
  "ignored": ["**/node_modules/**", "**/.next/**"],
  "techStack": {
    "framework": "nextjs",
    "database": "postgres",
    "auth": "clerk",
    "orm": "prisma"
  }
}

{
  "watchPaths": ["./src"],
  "ignored": ["**/node_modules/**", "**/dist/**"],
  "techStack": {
    "framework": "react",
    "ui": "tailwind"
  }
}

See .qawatch.json.example for all available options with documentation.

QA Watcher detects these production issues:

Safe patterns are automatically fixed:

Unsafe patterns (API keys, credentials) are flagged for manual review.

The Ralph Mode dashboard provides:

• Real-time progress - Watch issues get detected and fixed
• Kanban board - Issues organized by status (Detected → Fixing → Done)
• Cost tracking - Live cost counter with budget warnings
• Activity log - Timestamped log of all actions

Desktop notifications alert you to:

• Issues detected (with auto-fix count)
• Fixes applied
• Manual review needed
• Ralph Mode completion

QA Watcher uses Claude API calls. Typical costs:

A 4-hour manual code review session costs ~$200+ in developer time. Ralph Mode can achieve similar results overnight for $5-10.

{
  "ralph": {
    "budgetWarning": 5.00,
    "budgetHard": 20.00
  }
}

• Warning: Console notification at $5
• Hard stop: Ralph Mode stops at $20

# Watch mode (default)
npm run qa-watch

# Verbose output
npm run qa-watch -- --verbose

# Debug mode (stack traces)
npm run qa-watch -- --debug

# Auto-fix mode
npm run qa-watch -- --fix

# Ralph mode (autonomous)
npm run qa-ralph

# Ralph with custom cycles
npm run qa-watch -- --ralph --max-ralph-cycles 5

# Ralph without dashboard
npm run qa-watch -- --ralph --no-dashboard

# Show current config
npm run qa-watch -- --show-config

# Scan staged files (for pre-commit)
npm run qa-scan-staged

Automatically check staged files before each commit.

npm run qa-setup-hooks

This installs a git pre-commit hook that:

• Scans only staged .ts, .tsx, .js, .jsx files (fast)
• Blocks commits with critical issues (API keys, secrets)
• Shows warnings for non-critical issues (console.log)
• Allows commit if scan fails (fails open - won't block you)

1. You run git commit
2. Hook scans your staged files with Claude
3. If critical issues found → commit blocked with details
4. If only warnings → commit allowed with warning list
5. If scan fails → commit allowed (errors don't block)

To skip the check for a single commit:

git commit --no-verify

# Delete the hook
rm .git/hooks/pre-commit

# Or restore your original hook
mv .git/hooks/pre-commit.backup .git/hooks/pre-commit

Track historical QA data, trends, and ROI across all your review sessions.

When running Ralph Mode, the dashboard opens automatically. Click "QA Metrics" in the header to access analytics.

Or access directly at: http://localhost:3000/metrics

The metrics dashboard includes:

• Issues Over Time - Line chart showing found vs fixed issues
• Issues by Severity - Doughnut chart (critical/high/medium)
• Cost Over Time - Cumulative cost tracking
• Issues by Type - Bar chart of issue categories

Click "Export JSON" on the metrics page to download the raw metrics data for external analysis or reporting.

Metrics are stored in qa-reviews/metrics.json and persist across sessions. The file is append-only (up to 1000 sessions) to prevent data loss.

Define your own detection patterns without modifying QA Watcher code.

1. Rules live in .qawatch/rules/ directory (auto-created on first run)
2. Each rule is a JSON file with the pattern definition
3. Rules are loaded automatically on each scan

{
  "name": "my-custom-rule",
  "enabled": true,
  "pattern": "// HACK:",
  "severity": "medium",
  "type": "quality",
  "message": "HACK comment found - technical debt should be tracked",
  "fix": "Create issue to address technical debt",
  "autoFixable": false,
  "files": ["*.ts", "*.tsx"],
  "ignoreFiles": ["*.test.*"]
}

Literal string:

{ "pattern": "// TODO:" }

Regular expression (wrap in forward slashes):

{ "pattern": "/console\\.(log|warn|error)/" }

# List all rules (built-in + custom)
npm run qa-rules:list

# Validate custom rules
npm run qa-rules:validate

QA Watcher includes example rules in .qawatch/rules/:

• example-rule.json - Documented template (disabled by default)
• no-hardcoded-colors.json - Detect hex colors in code
• no-direct-dom.json - Detect DOM manipulation in React

QA Watcher supports both file-level and line-level ignores.

Create a .qaignore file in your project root to exclude files from QA review:

# Ignore all test files
**/*.test.ts
**/*.spec.ts

# Ignore directories
node_modules/
dist/

# Ignore specific files
legacy-code.js

# Negate (include despite previous rules)
!src/critical.test.ts

Pattern Syntax:

Add comments in your source code to skip specific lines or blocks:

// Skip the next line
// qa-ignore-next-line
const API_KEY = 'sk_test_123';

// Skip this line
const url = 'http://localhost:3000'; // qa-ignore

// Skip a block
/* qa-ignore-start */
const debug = true;
console.log('debug mode');
/* qa-ignore-end */

// Skip specific rule
// qa-ignore: hardcoded-localhost
const devUrl = 'http://localhost:8080';

// Skip multiple rules
// qa-ignore: console-log, debugger-statement
console.log('intentional');

Inline Ignore Reference:

1. Copy the example file: cp .qaignore.example .qaignore
2. Edit .qaignore to match your project needs
3. Use inline comments for intentional exceptions

❌ Claude CLI not found at: C:\...\claude.exe
   → Install Claude Code from: https://claude.ai/download

Solution: Install Claude Code CLI or update the path in config.

❌ Claude API rate limit exceeded
   → Wait a few minutes before retrying

Solution: Wait 2-5 minutes. QA Watcher auto-retries with exponential backoff.

⚠️ Watch path: Directory not found: ./src

Solution: Update watchPaths in .qawatch.json to match your project structure.

For detailed error information:

npm run qa-watch -- --debug

Debug mode shows:

• Full stack traces
• Detailed error context
• Verbose logging

• Review logs: ./qa-reviews/review-*.json
• Error log: ./qa-reviews/errors.log
• Master log: ./qa-reviews/master-log.jsonl

production-qa-watcher/
├── production-qa-watcher.js   # Main watcher script
├── dashboard-server.js        # Ralph Mode dashboard server
├── public/
│   └── index.html            # Dashboard UI
├── qa-reviews/               # Generated logs and reports
├── test-cases/               # Example files for testing
├── .qawatch.json             # Your config (generated)
├── .qawatch.json.example     # Config documentation
└── package.json

Contributions welcome! Areas for improvement:

• Additional detection patterns
• New auto-fix capabilities
• Dashboard enhancements
• Documentation improvements

MIT License - See LICENSE for details.

Built with:

• Claude Code - AI-powered code analysis
• Chokidar - File watching
• Express - Dashboard server
• node-notifier - Desktop notifications