BugZero

BugZero is an autonomous, AI-powered CLI tool for automatic build error detection and repair. It runs your build pipeline, parses compiler and linter output, invokes an LLM to generate a surgical code fix, applies it safely with a backup, and re-runs validation — looping until your project builds successfully or the attempt limit is reached.

Built for developers who want zero-downtime repair cycles, automated CI/CD recovery, and production-grade error resolution without manual debugging.

Why BugZero?

Modern applications fail at build and deployment time for reasons that are repetitive, predictable, and ultimately fixable by a knowledgeable agent. BugZero bridges the gap between raw compiler output and working code — automatically.

• No more debugging the same TypeScript error twice. The agent reads the stack trace, finds the file, generates the fix, and verifies it.
• Safe by design. Every file modified gets a .opspilot.bak backup before any change is applied.
• Model agnostic. Works with DeepSeek, Claude, Gemini, GPT-4o, Llama, or any model available on OpenRouter.
• Feedback loop included. The LangGraph state machine retries intelligently until the build passes or the max attempts threshold is hit.

How it Works

bugzero rescue
      |
      v
 Run Build + Lint + Tests
      |
      v
 Any failures? ---- No ---> Build already passing. Exit cleanly.
      |
     Yes
      |
      v
 Capture and parse error logs
      |
      v
 Prompt selected LLM via LangGraph Agent
      |
      v
 Parse structured fix suggestion (JSON)
      |
      v
 Apply search-and-replace patch (with .bak backup)
      |
      v
 Re-run build to verify the fix
      |
      v
 Build fixed? --- Yes ---> Print fix details. Exit success.
      |
      No
      |
      v
 Max attempts reached? -- Yes ---> Exit with failure logs.
      |
      No
      |
      +-------------------> Prompt LLM again (next attempt)

Key Features

| Feature | Description | |---|---| | Autonomous repair loop | Runs analyze, patch, verify in a stateful LangGraph graph | | Multi-model support | DeepSeek, Claude, GPT-4o, Gemini, Llama via OpenRouter | | Framework detection | Automatically identifies your project's tooling setup | | Safe file patching | Every modified file receives a .opspilot.bak backup | | Error type parsing | Parses TypeScript, ESLint, and Jest error formats | | Dry-run mode | Analyze and report without writing any files | | Local model config | Save preferred model to .bugzerorc per project |

Installation

Install globally from the NPM registry:

npm install -g bugzero

Setup

BugZero requires an OpenRouter API key to call AI models. Set it as an environment variable before running any command.

Linux / macOS:

export OPENROUTER_API_KEY="your_openrouter_api_key_here"

Windows (PowerShell):

$env:OPENROUTER_API_KEY="your_openrouter_api_key_here"

Or create a .env file in the project root you are targeting:

OPENROUTER_API_KEY=your_openrouter_api_key_here

Commands

bugzero hunt

Run build, lint, and test checks. Reports all failures without modifying any files.

bugzero hunt --path /path/to/your/project

bugzero rescue

Run the full AI-powered repair loop. Detects build failures, generates precise code patches, applies them, and verifies the result.

bugzero rescue --path /path/to/your/project

Options:

| Flag | Short | Default | Description | |---|---|---|---| | --path <dir> | -p | . | Path to the target project | | --max-attempts <n> | -n | 3 | Maximum AI fix iterations before giving up | | --dry-run | | false | Analyze only — no files will be written |

bugzero vibe

Interactively select which AI model to use. Fetches the current model list from OpenRouter, lets you pick one, and saves the selection to a local .bugzerorc config file.

bugzero vibe

Supported models (curated list, plus custom entry):

• DeepSeek V3 / DeepSeek R1
• Anthropic Claude 3.5 Sonnet
• Google Gemini 2.5 Pro / Flash
• OpenAI GPT-4o
• Meta Llama 3.3 Instruct

Configuration

BugZero reads a .bugzerorc JSON file in your target project directory to pick up model preferences:

{
  "model": "deepseek/deepseek-chat"
}

This file is created automatically when you run bugzero vibe.

Development Setup

Clone the repository and install dependencies. This project uses a pnpm monorepo managed by Turborepo.

Prerequisites

• Node.js 18 or later
• pnpm

Install

pnpm install

Build all packages

pnpm build

Run commands locally without installing globally

pnpm hunt --path ./demo-project
pnpm rescue --path ./demo-project
pnpm vibe

Monorepo package structure

| Package | Role | |---|---| | packages/cli | CLI entrypoint (Commander) | | packages/core | Orchestrates build and fix flow | | packages/agents | LangGraph state machine (analyze, patch, verify) | | packages/ai-provider | OpenRouter HTTP client | | packages/analyzers | Runs build/lint/test and parses output | | packages/patcher | Applies search-and-replace patches with backup | | packages/prompts | LLM prompt templates | | packages/config | Env loading and local .bugzerorc config store | | packages/shared | Shared TypeScript types |

Error Handling

BugZero provides clear, actionable output for common failure modes:

| Error | Message | |---|---| | Invalid API key (401) | Prompts you to check your OPENROUTER_API_KEY | | Rate limit exceeded (429) | Prompts you to check your OpenRouter credit balance | | Model not found | Displays the invalid model ID and suggests running bugzero vibe | | Patch not applied | Reports exact mismatch between AI suggestion and file content | | Max attempts reached | Exits cleanly with the last error log for manual review |

Author

Saksham Agarwal

• GitHub: @Saksham1800t
• LinkedIn: Saksham Agarwal
• Email: [email protected]

Support

If BugZero saved you debugging hours in production or deployment pipelines, consider buying the author a coffee.