🛡️ Bug Detector

AI-powered local code guardian that detects bugs on every file save — using a local vector database and Gemini API.

What it does

Bug Detector watches your project files. Every time you save a file, it:

1. Re-indexes the changed code into a local vector database
2. Finds related code across your project using semantic search
3. Detects all chunks changed in your current session
4. Sends targeted context to Gemini AI for analysis
5. Reports bugs, affected areas, and suggestions instantly

No cloud storage. No sending your entire codebase anywhere. Everything runs locally except the final Gemini analysis call.

Features

• 🔍 Bug detection — finds logic bugs, type mismatches, and potential crashes
• 🗺️ Blast radius — shows which other files your change could affect
• 🔄 Session-aware — tracks all changes made in the last 2 hours, not just the last save
• 🏗️ Cross-stack detection — matches C# backend routes with TypeScript frontend fetch calls
• 💾 Local vector DB — SQLite + embeddings, runs entirely on your PC
• 🤖 Local model fallback — use deepseek-coder via Ollama instead of Gemini (no API cost)
• 📊 Terminal dashboard — live updating UI with --dashboard flag
• 🔷 TypeScript + C# — supports both languages in the same project

Requirements

• Node.js 18+
• Ollama — installed automatically on first run
• Gemini API key — free at aistudio.google.com
• .NET SDK — only needed if you have C# files

Installation

npm install -g bug-detector

Setup

1. Create a .env file in your project root:

GEMINI_API_KEY=your_gemini_api_key_here
CODEGUARD_MODE=gemini

Get your free Gemini API key at aistudio.google.com.

2. Index your project:

codeguard init

This scans your project, generates embeddings, and builds a local vector database in .codeguard/db.sqlite.

Add .codeguard/ and .env to your .gitignore.

3. Start watching:

codeguard watch

Or with the live dashboard:

codeguard watch --dashboard

Now save any file and Bug Detector will analyse it instantly.

Commands

| Command | Description | |---|---| | codeguard init | Index your project for the first time | | codeguard watch | Watch files and detect bugs on save | | codeguard watch --dashboard | Watch with live terminal dashboard | | codeguard status | Show indexed files and stored routes |

Analysis output

─────────────────────────────────
  CODEGUARD ANALYSIS REPORT
─────────────────────────────────
  🔴 Line 42: Missing null check before accessing user.profile
  🟡 Line 67: This function mutates the input array directly

  ⚠ Affected areas:
    src/api/user.ts → getProfile
    Reason: Calls getUserById which may return null

  💡 Suggestions:
    • Add null guard before accessing user.profile
    • Consider returning a copy of the array instead
─────────────────────────────────

Severity levels:

• 🔴 Error — likely to cause a crash or incorrect behavior
• 🟡 Warning — potential issue, worth reviewing
• 🔵 Info — improvement suggestion

Using local model (no API cost)

If you want to run fully offline without Gemini API:

CODEGUARD_MODE=local

This uses deepseek-coder via Ollama. Quality is lower than Gemini but works with no internet and no API limits.

Pull the model first:

ollama pull deepseek-coder

How it works

codeguard init
      ↓
Scans project → extracts functions/classes/routes
      ↓
Generates embeddings via Ollama (local, no cost)
      ↓
Stores in SQLite vector database (.codeguard/db.sqlite)
      ↓
Builds dependency graph (what imports what)

On every file save:
      ↓
Re-indexes changed file
      ↓
Fetches all chunks changed in last 2 hours
      ↓
Semantic search for related context
      ↓
Sends to Gemini → bug report in terminal

Supported languages

| Language | Parser | Features | |---|---|---| | TypeScript / TSX | ts-morph | Functions, classes, interfaces, hooks, fetch calls | | C# | Roslyn | Classes, methods, interfaces, enums, HTTP routes |

Cross-stack detection

For full-stack projects with a C# backend and TypeScript frontend, Bug Detector matches your API routes with your frontend fetch calls and warns you about mismatches:

⚠ Cross-stack mismatch:
  [GET] /api/users → UserController.GetUsers()
  Frontend: src/api/users.ts calls /api/user (missing 's')

gitignore

Add these to your .gitignore:

.codeguard/
.env

Tech stack

• Embeddings — Ollama + nomic-embed-text (local, free)
• Vector search — SQLite + sqlite-vec
• TypeScript parser — ts-morph
• C# parser — Roslyn (.NET)
• AI analysis — Gemini API / deepseek-coder
• File watching — chokidar
• Dashboard — ink (React for terminal)

License

MIT