Bug Officer 🔍

AI-powered error detection and fix suggestions for your terminal. Works online with Gemini or completely offline with Ollama. Supports TypeScript, JavaScript, Python, Rust, Go, and Java.

Why Bug Officer?

Every developer has been stuck staring at a wall of terminal errors. Bug Officer reads those errors automatically, understands what went wrong, and tells you exactly what to fix — right in your terminal.

No copy-pasting into ChatGPT. No switching tabs. Just run one command.

Demo

$ officer analyze

✔ Detected: TypeScript, JavaScript/ESLint
✔ Found 9 error(s) across 2 language(s)
✔ Code context loaded.

  Errors detected:
  ─────────────────────────────────────────
  1. [tsc TS7006] Parameter 'name' implicitly has an 'any' type.
     src/index.ts:10

  2. [tsc TS2683] 'this' implicitly has type 'any'
     src/timer.ts:77

  ...

✔ Analysis complete in 19s via Gemini (online)

╭───────────────────────────────────╮
│   BUG OFFICER — Analysis Report   │
╰───────────────────────────────────╯

  Summary
  Multiple TypeScript errors due to missing type annotations
  and incorrect this context binding

  Severity:    CRITICAL
  Root Cause:  Missing explicit types and arrow function usage

  Suggested Fixes
  ✔ 1. src/index.ts:10
     Add type annotation to parameter
     Replace with: function greet(name: string) {

  ✔ 2. src/timer.ts:77
     Replace regular function with arrow function
     Replace with: setInterval(() => {

Features

• 🔍 Auto-detects your project language automatically
• 🤖 AI-powered fixes with exact corrected code
• 📡 Online mode via Gemini API — fast and accurate
• 🔒 Offline mode via Ollama — no internet needed, runs locally
• 👁️ Watch mode — re-analyzes automatically on every file save
• 🎨 Beautiful output with colors, patterns, and structured fixes
• ⚡ Code context — sends actual code around errors for better fixes
• 🌐 Multi-language — TypeScript, JavaScript, Python, Rust, Go, Java

Install

npm install -g bug-officer

Quick Start

Online mode (uses Gemini API)

# step 1 — get a free API key
# https://aistudio.google.com

# step 2 — create .env file in your project
echo "GEMINI_API_KEY=your_key_here" > .env

# step 3 — set mode
officer mode online

# step 4 — run
officer analyze

Offline mode (uses Ollama — no internet needed)

# step 1 — install Ollama
# https://ollama.ai/download

# step 2 — download a code model (one time only)
ollama pull qwen2.5-coder:1.5b

# step 3 — set mode
officer mode offline

# step 4 — run
officer analyze

All Commands

| Command | Description | |---|---| | officer analyze | Auto-scan project for errors | | officer analyze --run "cmd" | Run any command and analyze output | | officer watch | Watch files, auto-analyze on every save | | officer mode online | Always use Gemini API | | officer mode offline | Always use Ollama locally | | officer mode auto | Auto-detect best available provider | | officer status | Check which providers are available | | officer help | Show all commands with examples | | officer version | Show current version |

Usage Examples

# analyze your whole project automatically
officer analyze

# run your build command and analyze errors
officer analyze --run "npm run build"
officer analyze --run "cargo build"
officer analyze --run "python app.py"

# watch mode — re-analyzes every time you save a file
officer watch

# check what is configured
officer status

# switch between online and offline anytime
officer mode online
officer mode offline

How It Works

officer analyze
      │
      ▼
Scans your project folder
Detects languages by signature files
(tsconfig.json → TypeScript)
(.eslintrc.json → JavaScript)
(requirements.txt → Python)
(Cargo.toml → Rust)
(go.mod → Go)
(pom.xml → Java)
      │
      ▼
Runs each language's compiler/linter
tsc --noEmit
eslint . --format compact
python main.py
cargo build
      │
      ▼
Parses error output
Each language has its own parser
Extracts file, line, column, message
      │
      ▼
Reads actual code around each error
Sends error + surrounding code to AI
      │
      ▼
AI analyzes everything
Returns structured JSON response
summary, severity, rootCause,
patterns, suggestions, correctedCode
      │
      ▼
Prints everything beautifully
in your terminal

Supported Languages

| Language | Detected by | Tool used | |---|---|---| | TypeScript | tsconfig.json | tsc --noEmit | | JavaScript | .eslintrc.* | eslint . --format compact | | Python | *.py / requirements.txt | python <entry> | | Rust | Cargo.toml | cargo build | | Go | go.mod | go build ./... | | Java (Maven) | pom.xml | mvn compile | | Java (Gradle) | build.gradle | gradle build |

Online vs Offline

| Feature | Online (Gemini) | Offline (Ollama) | |---|---|---| | Requires internet | Yes | No | | Requires API key | Yes | No | | Speed | ~20-35 seconds | ~15-50 seconds | | Accuracy | Higher | Good | | Cost | Free tier available | Completely free | | Setup | Add API key to .env | Install Ollama + pull model |

Requirements

• Node.js 18 or higher
• For online mode: Gemini API key (free at https://aistudio.google.com)
• For offline mode: Ollama (free at https://ollama.ai)

Project Structure

src/
  ├── ai/
  │   ├── client/
  │   │   ├── index.ts          → picks Gemini or Ollama
  │   │   ├── geminiClient.ts   → Gemini API integration
  │   │   └── ollamaClient.ts   → Ollama local integration
  │   └── pipeline/
  │       └── analyzerPipeline.ts → orchestrates AI analysis
  ├── cli/
  │   ├── commands/
  │   │   ├── debug.ts          → analyze command
  │   │   ├── watch.ts          → watch command
  │   │   ├── modeCommand.ts    → mode + status commands
  │   │   └── helpCommand.ts    → help command
  │   └── index.ts              → CLI entry point
  ├── config/
  │   └── configManager.ts      → saves user mode preference
  ├── core/
  │   └── contextBuilder.ts     → builds context for AI
  ├── output/
  │   └── formatter.ts          → terminal output formatting
  ├── parsers/
  │   ├── languages/
  │   │   ├── tscParser.ts      → TypeScript error parser
  │   │   ├── eslintParser.ts   → ESLint error parser
  │   │   ├── pythonParser.ts   → Python error parser
  │   │   ├── rustParser.ts     → Rust error parser
  │   │   ├── goParser.ts       → Go error parser
  │   │   ├── javaParser.ts     → Java error parser
  │   │   └── genericParser.ts  → fallback parser
  │   ├── index.ts              → parser router + enrichErrors
  │   └── responseParser.ts     → parses AI JSON response
  ├── prompts/
  │   └── promptBuilder.ts      → builds prompts for Gemini/Ollama
  ├── services/
  │   ├── terminalService.ts    → runs compilers and captures output
  │   └── watchService.ts       → file watching with chokidar
  ├── types/
  │   └── index.ts              → shared TypeScript types
  └── utils/
      └── projectDetector.ts    → detects project languages

Contributing

See CONTRIBUTING.md for how to:

• Add support for a new language
• Add a new AI provider
• Run the project locally

Roadmap

• [ ] Auto-apply fixes directly to files with --fix flag
• [ ] VS Code extension
• [ ] Support for C#, Ruby, PHP
• [ ] GitHub Actions integration
• [ ] Fix history and analytics

License

MIT © Sourav Mishra

Author

Built by Sourav Mishra

If this tool helped you, consider giving it a ⭐ on GitHub!