Buggy

A multi-agent system that autonomously analyzes code, proves bugs exist with formal certificates, generates repairs, and validates patches against overfitting — all coordinated over the Model Context Protocol (MCP). Unlike traditional debuggers that rely on breakpoints and manual inspection, this system produces cryptographically-verifiable proof-of-failure certificates before attempting any repair.

Quick Start

# Install
npm install buggy

# Initialize in your project
cd /path/to/your/project
npx buggy init

# Edit .debugger.yaml to match your project setup, then:
npx buggy analyze src/payments.ts
npx buggy investigate processPayment --file src/payments.ts

Kiro Integration

Buggy now works automatically inside Kiro — your team doesn't need to run commands manually. Once configured, every file save, every AI-generated edit, and every spec task is automatically analyzed for bugs with zero developer effort.

How It Works

Buggy ships with 6 Kiro hooks that fire on IDE events. When a hook triggers, Kiro's agent calls Buggy's MCP tools behind the scenes, interprets the results, and either reports findings or applies fixes automatically.

Hooks (Automatic Bug Detection)

Hook	Trigger	What It Does
buggy-on-save	File saved	Analyzes the saved file for bugs immediately
buggy-post-write	Kiro writes code	Verifies AI-generated code for correctness
buggy-pre-task	Before spec task execution	Scans relevant files before changes are made
buggy-auto-fix	Agent completes work	Self-healing loop — re-checks and fixes (max 3 iterations)
buggy-deep-scan	User-triggered	Full project scan across all source files
buggy-spec-evolution	After task completion	Verifies new implementations match specifications

What Developers Experience

• Save a file → bugs are surfaced in seconds, no command needed
• Kiro writes code → Buggy verifies it before you even review
• Start a spec task → risky files are pre-scanned for existing issues
• Complete a task → implementation is verified against the spec

Deploying to Your Team

Commit the .kiro/ folder to your repository. Every team member who opens the project in Kiro gets automatic bug detection with no setup:

git add .kiro/
git commit -m "Add Buggy hooks and steering files for automatic bug detection"

Steering Files (Advanced Workflows)

Buggy includes 8 steering files that guide Kiro's behavior during debugging workflows. Four are always active (cross-file impact analysis, bug trend tracking, onboarding warnings, core debugging workflow), and four activate on demand for PR reviews, git-diff analysis, spec inference, and TypeScript type narrowing suggestions.

See the Usage Guide for the full list and customization options.

---

Installation

npm install buggy

Or install globally for CLI access:

npm install -g buggy
buggy --help

Requirements

• Node.js >= 18.0.0
• A Tree-sitter grammar for your language
• An LSP server for symbol resolution (optional but recommended)

Integration Guide

1. Add configuration to your project

Run buggy init in your project root. This creates:

• .debugger.yaml — configuration file
• .debugger/ — working directory for the graph database

2. Configure for your language

Edit .debugger.yaml to match your project:

language: typescript
parser:
  command: tree-sitter-typescript
lsp:
  command: typescript-language-server
sandbox:
  runtime: node
  memory_limit_mb: 512
  timeout_seconds: 60

3. Add to .gitignore

# Buggy
.debugger/

Programmatic API

import { ProofDebugger } from 'buggy';

const debugger_ = new ProofDebugger({
  projectRoot: '/path/to/your/project',
  language: 'typescript', // optional override
  sandbox: { memory_limit_mb: 1024 }, // optional override
});

await debugger_.initialize();

// Investigate a specific function
const report = await debugger_.investigate({
  functionId: 'processPayment',
  filePath: 'src/payments.ts',
  specification: {
    preconditions: ['amount > 0'],
    postconditions: ['result.status === "success" || result.status === "failed"'],
    parameters: [{ name: 'amount', type: 'number' }],
    return_type: 'PaymentResult',
  },
});

// Access results
console.log(report.status);
// → 'confirmed_and_repaired' | 'confirmed_no_repair' | 'unconfirmed' | 'halted'

console.log(report.proof);           // The proof-of-failure certificate
console.log(report.approved_patches); // Patches that passed overfitting check

// Run a single parse
const parseResult = await debugger_.parse('src/payments.ts');
console.log(parseResult.cst);    // Full concrete syntax tree
console.log(parseResult.errors); // Syntax errors with locations

// Query the semantic graph
const { callees, edges } = await debugger_.queryCallees('processPayment');

// Query a specific node
const node = debugger_.queryNode('node_42');

// Get file subgraph
const { nodes, edges: fileEdges } = debugger_.queryFileGraph('src/payments.ts');

// Check investigation status
const status = debugger_.getStatus(report.id);

// Halt a running investigation
debugger_.halt(report.id);

// Shutdown (closes DB, LSP connections)
await debugger_.shutdown();

ProofDebugger Options

interface ProofDebuggerOptions {
  projectRoot: string;        // Required: path to your project
  language?: string;          // Override auto-detected language
  configPath?: string;        // Custom .debugger.yaml path
  dbPath?: string;            // Custom database path
  sandbox?: {
    memory_limit_mb?: number;
    timeout_seconds?: number;
    egress_policy?: 'deny' | 'allow_host_only';
  };
  probe?: {
    search_budget?: number;
    max_refinement_iterations?: number;
  };
}

CLI Reference

buggy init

Creates a .debugger.yaml template and .debugger/ directory in the current working directory.

buggy init
buggy init --json  # Machine-readable output

buggy analyze <file>

Parses a file using Tree-sitter and displays the semantic graph summary.

buggy analyze src/payments.ts
buggy analyze src/payments.ts --verbose   # Show CST depth-2 summary
buggy analyze src/payments.ts --json      # Full JSON output

buggy investigate <function> --file <path>

Runs the full investigation pipeline (Parse → Prove → Repair → Classify) on a function.

buggy investigate processPayment --file src/payments.ts
buggy investigate processPayment -f src/payments.ts --verbose
buggy investigate processPayment -f src/payments.ts --json

buggy status <id>

Shows the current status of a running or completed investigation.

buggy status inv_1234567890_abc1234
buggy status inv_1234567890_abc1234 --json

buggy halt <id>

Halts a running investigation, preserving intermediate results.

buggy halt inv_1234567890_abc1234

Global Options

Flag	Description
--json	Output results as JSON (machine-readable)
--verbose	Enable detailed logging and extended output
--help, -h	Show help message

Configuration Reference

The .debugger.yaml file controls all aspects of the debugger. Here's the full schema:

# Required
version: "1.0"
language: typescript    # Primary project language

# Parser configuration
parser:
  command: tree-sitter-typescript  # Tree-sitter grammar to use
  grammar_path: ./custom.wasm     # Optional: path to custom grammar

# Language Server Protocol
lsp:
  command: typescript-language-server
  initialization_options:          # Optional: passed to LSP on init
    preferences:
      includeInlayParameterNameHints: "all"

# Sandbox execution environment
sandbox:
  runtime: node                    # Execution runtime (node, python, deno, bun)
  memory_limit_mb: 512             # 64-8192 MB
  timeout_seconds: 60              # 1-300 seconds
  egress_policy: deny              # deny | allow_host_only

# Oracle violation detectors
oracles:
  timeout_threshold_seconds: 10    # 1-300 seconds
  crash_detection: true
  overflow_detection: true
  determinism_check_count: 5       # 1-100 runs

# PROBE loop configuration
probe:
  search_budget: 100               # Max property candidates
  max_refinement_iterations: 10    # Max iterations per property

# Optional: custom plug-ins
plugs:
  parsing: ./plugs/parser
  oracles:
    - ./plugs/memory-oracle
  repair: ./plugs/repair-strategy
  sandbox_executor: ./plugs/sandbox

Defaults

Field	Default
lsp.initialization_options	{}
sandbox.egress_policy	deny
plugs	undefined (no custom plugs)

Architecture Overview

The system consists of five specialized agents coordinated by an orchestrator:

┌──────────────────────────────────────────────────────────────┐
│                     Agent Orchestrator                        │
│  (Coordinates sequential pipeline + sandbox concurrency)     │
└─────────┬──────────┬──────────────┬──────────────┬───────────┘
          │          │              │              │
    ┌─────▼─────┐ ┌─▼──────────┐ ┌▼──────────┐ ┌─▼───────────┐
    │  Parser   │ │ Bug-Proving │ │  Repair   │ │ Classifier  │
    │  Agent    │ │   Agent     │ │  Agent    │ │   Agent     │
    └───────────┘ └─────────────┘ └───────────┘ └─────────────┘
          │              │              │              │
          └──────────────┴──────────────┴──────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   Sandbox Agent   │
                    │  (up to 4 conc.)  │
                    └───────────────────┘

Pipeline flow:

1. Parser Agent — Tree-sitter CST parsing, symbol resolution via LSP, call graph construction
2. Bug-Proving Agent — PROBE loop + fuzzing + specification refinement → proof-of-failure certificate
3. Repair Agent — AST-aware patch generation with multi-stage filtering (compile → emulate → test)
4. Classifier Agent — PRISM-APCC overfitting detection using AST difference vectors
5. Sandbox Agent — Isolated execution with resource limits, available on-demand to all agents

Data layer:

• SQLite graph database (WAL mode) stores CST nodes, edges, symbol resolutions, proofs, and patches
• All inter-agent data flows through typed MCP tool calls

Extending with Custom Plugs

The plug system lets you override default agent behavior without modifying core code.

Creating a Parser Plug

import type { ParsingPlug } from 'buggy';

export const myParser: ParsingPlug = {
  name: 'my-custom-parser',
  parse(source: string, filePath: string) {
    // Your custom parsing logic
    return { cst, errors, duration_ms, file_path: filePath };
  },
};

Creating an Oracle Plug

import type { OraclePlug } from 'buggy';

export const memoryOracle: OraclePlug = {
  name: 'memory-leak-detector',
  detect(executionResult) {
    // Analyze execution for memory leaks
    return violations;
  },
};

Creating a Repair Plug

import type { RepairPlug } from 'buggy';

export const mlRepair: RepairPlug = {
  name: 'ml-based-repair',
  generatePatches(proof, target) {
    // ML-based patch generation
    return patches;
  },
};

Registering Plugs

Add plug paths to .debugger.yaml:

plugs:
  parsing: ./plugs/my-custom-parser
  oracles:
    - ./plugs/memory-leak-detector
  repair: ./plugs/ml-based-repair

The debugger loads and validates plugs at startup, falling back to defaults if a plug fails to load.

Development

# Build
npm run build

# Run tests
npm test

# Run specific test suites
npm run test:unit
npm run test:properties
npm run test:integration

# Run the CLI locally
node dist/cli.js --help

License

MIT