👻 Hauntr

Your AI codebase engineer

Hauntr scans your codebase, finds issues, and uses AI to explain exactly why they're a problem — with a ready-to-paste fix.

Installation · Usage · Auto-fix · AI Mode · Configuration · Rules · Custom Rules

Why Hauntr?

Most linters tell you what is wrong. Hauntr tells you why it matters and shows you the fix — powered by AI.

hauntr scan --ai

  src/components/Dashboard.jsx
  ⚠  "useEffect" is imported but never used   unusedImports

       Why: Unused imports increase bundle size and make it harder for other
       developers to understand what a component actually depends on.

       Fix:
         import { useState } from 'react';

Installation

npm install -g hauntr

Requires Node.js 18+.

Usage

# Scan current directory
hauntr scan

# Scan a specific path
hauntr scan ./src

# AI-powered explanations and fixes
hauntr scan --ai

# Auto-fix fixable issues
hauntr fix

# Save a markdown report
hauntr scan --output markdown

# Output raw JSON
hauntr scan --output json

# Create a config file
hauntr init

Auto-fix

Hauntr can automatically fix certain issues in place — no copy-pasting required.

# Fix all auto-fixable issues in the current directory
hauntr fix

# Fix a specific path
hauntr fix ./src

# Preview what would be fixed without writing any files
hauntr fix --dry-run

# Scan, report, and fix in one shot
hauntr scan --fix

# Scan, report, and preview fixes without writing files
hauntr scan --fix --dry-run

Example output:

✔  Fixed 3 issues across 2 files
   src/components/Dashboard.jsx
   src/utils/helpers.js

⚠  1 issue could not be auto-fixed — run `hauntr scan` to review

Only rules marked as fixable in the Built-in Rules table support auto-fix. Custom rules can opt in by implementing a fix(content, issues) method — see Writing Custom Rules.

AI Mode

Hauntr uses AI to enrich every issue it finds with:

• Why — a plain-English explanation of the risk
• Fix — a minimal corrected code snippet, ready to paste

To use AI mode, set your API key and pass the --ai flag:

# Groq (free)
export GROQ_API_KEY="gsk_..."
hauntr scan --ai

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
hauntr scan --ai

Get a free Groq key at console.groq.com.

Configuration

Create a hauntr.config.js in your project root, or run hauntr init to scaffold one:

// hauntr.config.js
export default {
  rules: {
    unusedImports: 'warn',
    largeComponents: { severity: 'warn', maxLines: 300 },
    readmeCheck: 'error',
  },
  ignore: ['dist', 'coverage', '*.test.js'],
};

Severity levels

| Value | Behaviour | |---|---| | 'error' | Exits with code 1, fails CI | | 'warn' | Reported but does not fail CI | | 'off' | Rule disabled |

Built-in Rules

| Rule | What it catches | Auto-fixable | |---|---|---| | unusedImports | Imported bindings never referenced in the file | ✅ | | largeComponents | Component files over a line threshold (default: 300) | ❌ | | readmeCheck | Missing README or missing Installation/Usage sections | ❌ |

Full documentation for each rule: docs/rules.md

Writing Custom Rules

Every rule is a plain JS object with a run method. Register it in your config:

// my-rules/noConsole.js
export const noConsole = {
  meta: {
    name: 'noConsole',
    description: 'Disallows console.log statements in production code.',
    fixable: false,
  },

  run(file, options = {}) {
    const issues = [];
    const lines = file.content.split('\n');

    lines.forEach((line, idx) => {
      if (/console\.(log|warn|error)/.test(line)) {
        issues.push({
          rule: 'noConsole',
          severity: options.severity ?? 'warn',
          message: 'Unexpected console statement',
          file: file.path,
          line: idx + 1,
        });
      }
    });

    return issues;
  },
};

// hauntr.config.js
import { registry } from 'hauntr/rules';
import { noConsole } from './my-rules/noConsole.js';

registry.register('noConsole', noConsole);

export default {
  rules: {
    noConsole: 'error',
  },
};

To make a custom rule auto-fixable, set fixable: true in meta and add a fix(content, issues) method that returns the corrected file content:

export const myRule = {
  meta: {
    name: 'myRule',
    description: '...',
    fixable: true,
  },

  run(file, options = {}) { /* ... */ },

  fix(content, issues) {
    // Apply fixes to content and return the modified string
    return content;
  },
};

See CONTRIBUTING.md for the full rule API reference.

CI Integration

Hauntr exits with code 1 when any error-level issues are found, making it drop-in ready for GitHub Actions:

# .github/workflows/hauntr.yml
name: Hauntr

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g hauntr
      - run: hauntr scan

Contributing

Contributions are welcome — especially new rules. See CONTRIBUTING.md to get started.

git clone https://github.com/boyzliberty360/hauntr.git
cd hauntr
npm install
npm test

License

MIT © boyzliberty360