Ghost Debugger

Inspiration

Every developer has experienced that frustrating moment when code fails and you spend the next hour gathering context: reading stack traces, checking what changed in git, reviewing environment variables, and manually piecing together what went wrong. We wanted to eliminate that tedious process entirely.

The "it works on my machine" problem costs teams countless hours. We built Ghost Debugger to capture the complete error context automatically and leverage AI to diagnose and fix issues in seconds instead of hours.

What it does

Ghost Debugger is a CLI tool that wraps around any command. When your code fails, it captures everything needed to diagnose the issue:

• Complete stack trace with file locations and line numbers
• Git context (current branch, recent commits, modified files)
• Environment information (runtime versions, platform, dependencies)
• Relevant code snippets from the files involved
• System state at the moment of failure
• Then with a single command (kilo-ghost fix), it sends this rich context to Claude Sonnet 4.5 via the Kilo AI Gateway. The AI analyzes the error, explains the root cause, suggests a fix with a confidence score, and can even apply the fix automatically.

How we built it

We chose TypeScript for type safety and maintainability. The architecture is modular with clear separation of concerns:

• Capture System: Individual modules for stack trace parsing, git integration, environment detection, and file analysis
• Kilo Integration: Direct integration with Kilo AI Gateway using their API, sending structured prompts to Claude Sonnet 4.5
• Storage Layer: Local persistence of error snapshots in ~/.kilo-ghost/ for history and analysis
• CLI Interface: Commander.js for the command-line interface with commands for run, fix, auth, and history The prompt engineering was crucial. We crafted a detailed system prompt that gives Claude the full context: error details, code snippets, git history, and environment info. The AI responds with structured JSON containing root cause analysis, confidence scores, and actionable fixes.

We used the Kilo AI Gateway's chat completions endpoint, which made integration straightforward while keeping costs incredibly low (about $0.006 per fix analysis).

Challenges we ran into

Stack trace parsing across languages: Different runtimes format errors differently. We built parsers for Node.js, TypeScript, and Python, handling various edge cases like source maps and async stack traces.

Git integration reliability: Reading git state while respecting .gitignore and handling repositories in various states required careful subprocess management and error handling.

Prompt engineering: Getting consistent, high-quality responses from the AI required iteration. We needed to provide enough context without overwhelming the model, and structure the prompt so responses were always parseable JSON.

File modification safety: Applying AI-suggested fixes automatically is powerful but risky. We implemented safeguards: creating backups, validating diffs, and offering preview mode before applying changes.

TypeScript CommonJS compatibility: Some dependencies had ESM/CommonJS conflicts. We resolved this by carefully selecting compatible versions and adding proper type declarations.

Accomplishments that we're proud of

We built a genuinely useful tool that we actually want to use ourselves. The workflow is seamless: run your command with kilo-ghost run, get an error, type kilo-ghost fix, and boom - you have an AI-powered diagnosis and suggested fix.

The integration with Kilo AI Gateway is production-ready, not a mock. Every fix analysis uses real AI, costs less than a penny, and provides genuinely helpful suggestions.

The codebase is clean, well-tested (7 test suites with good coverage), and properly documented. It's structured as a real open-source project with contribution guidelines, proper TypeScript configuration, and a clear architecture that others can extend.

We created a complete demo script that shows the full workflow in under 5 minutes, making it easy to understand the value proposition immediately.

What we learned

AI needs rich context: The difference between "here's an error message" and "here's the error with stack trace, git context, environment, and relevant code" is massive. Claude gives dramatically better suggestions when it has the full picture.

Kilo AI Gateway is powerful: The simplicity of their API combined with access to Claude Sonnet 4.5 made integration straightforward. The cost efficiency means this tool is practical for real daily use.

Developer tools need polish: Even if the core functionality works, the user experience matters. Clear command names, helpful error messages, progress indicators, and good documentation make the difference between a hackathon project and a tool people actually adopt.

Prompt engineering is a craft: Small changes in how we structured the prompt to Claude resulted in dramatically different response quality. Asking for structured JSON output with specific fields improved consistency significantly.

What's next for Ghost Debugger

VS Code Extension: Integrate directly into the editor. When you hit a breakpoint or exception, Ghost Debugger could analyze it inline and suggest fixes without leaving your IDE.

Streaming responses: Instead of waiting for the full AI analysis, stream the diagnosis in real-time so users see progress immediately.

Learning from history: Build a local cache of similar errors and their fixes. If you encounter the same type of error again, suggest the previous fix instantly without an API call.

Multi-language expansion: Add support for more languages (Java, Go, Rust) with specialized stack trace parsers and context capture for each ecosystem.

Team collaboration: Allow teams to share error snapshots and fixes. Build a knowledge base of common issues and their solutions across the organization.

CI/CD integration: When tests fail in CI, automatically capture context and post AI analysis as a comment on the pull request.

Built With

• commander.js
• git
• jest
• kilo
• node.js
• typescript