Stop Googling.
Understand your errors.
DeBugBuddy is a local-first CLI + TUI that explains errors in plain English, predicts issues before they break, and keeps your debugging history private.
Explain Fast
Plain-English fixes
Predict Issues
Before they break
Local-First
Privacy by default
Analytics
Track patterns
Everything you need to debug smarter
A comprehensive toolkit for understanding, predicting, and learning from your errors.
Explain Errors Instantly
Get plain-English explanations with fixes and examples. No more deciphering cryptic stack traces or searching through endless forum posts.
- Automatic language detection
- Context-aware explanations
- Code fix suggestions
- Example solutions included
Predict Issues
Static checks, pattern scans, and optional ML prediction catch bugs before they crash your program. Write better code proactively.
- 150+ error patterns
- ML-powered predictions
- Multi-file scanning
- Watch mode for real-time feedback
Local-First Privacy
Everything stays on your machine unless you explicitly opt into AI mode. Your code, your errors, your privacy.
- No data collection
- Offline-first design
- Optional AI enhancement
- Local history storage
History Analytics
Track frequent errors and languages over time. Identify patterns in your debugging workflow and improve your coding habits.
- Error frequency tracking
- Language statistics
- Time-based analytics
- Searchable history
Powerful CLI
Full-featured command-line interface with intuitive commands for explaining, predicting, watching, and searching.
- dbug explain
- dbug predict
- dbug watch
- dbug search
GitHub Integration
Search GitHub issues for similar errors, with repo scoping and exact matching for precision.
- Issue search
- Repo scoping
- Exact matching
- Closed issues support
Get started in seconds
A simple pip install is all you need to start debugging smarter.
Install the Package
Install DeBugBuddy using pip. It works with Python 3.8+ and has minimal dependencies.
pip install debugbuddy-cliRun Your First Command
After your Python script encounters an error, simply run dbug explain to get instant explanations.
python script.py && dbug explainLaunch the TUI
For a full-screen interactive experience, launch the Textual-based GUI with a single command.
debugbuddyConfigure (Optional)
Customize your experience with AI providers, history settings, and more.
dbug config ai_provider grokQuick Start Example
1. Create a test file with an error:
echo 'print(undefined_var)' > test.py2. Run it and explain the error:
python test.py; dbug explain3. Or predict errors before running:
dbug predict test.pyPowerful command-line interface
Every command you need to debug, predict, and learn from your errors.
dbug explain
Syntax
Description
Explain the most recent error message in plain English with fixes and examples.
Options
--aiUse AI provider for enhanced explanations--verboseShow detailed stack trace analysis--lang <language>Override detected languageExample
Sample Output
╔══════════════════════════════════════════════════════════════╗ ║ DeBugBuddy - Error Explanation ║ ╠══════════════════════════════════════════════════════════════╣ ║ Error: NameError: name 'undefined_var' is not defined ║ ║ ║ ║ Explanation: ║ ║ You're trying to use a variable 'undefined_var' that ║ ║ hasn't been defined yet in your code. ║ ║ ║ ║ Fix: ║ ║ • Define the variable before using it ║ ║ • Check for typos in the variable name ║ ║ • Ensure the variable is in scope ║ ╚══════════════════════════════════════════════════════════════╝
A beautiful terminal UI
Full-screen interface powered by Textual. Navigate between views without leaving your terminal.
Dashboard
Central hub showing recent errors, quick actions, and system status.
Keyboard-First
Navigate entirely with keyboard shortcuts
Split Panels
View multiple sections simultaneously
Integrated
No context switching needed
Syntax Highlighting
Beautiful code display built-in
Optional AI-powered explanations
Enhance your debugging with AI providers. Completely optional — everything works locally by default.
Privacy First
AI is opt-in only. Without configuration, DeBugBuddy uses local pattern matching with 150+ built-in patterns. Your code never leaves your machine unless you explicitly enable AI mode.
Choose a Provider
Configure OpenAI
Get an API Key
Visit the OpenAI website and create an API key from your account dashboard.
Configure DeBugBuddy
Run these commands to set up your provider:
Use AI-Enhanced Explanations
Add the --ai flag to any explain command:
API keys are stored locally in ~/.debugbuddy/config.json. They are never shared or transmitted except to your chosen AI provider.
7 languages supported
With 160+ error patterns and growing. More languages coming every release.
Python
JavaScript
TypeScript
C/C++
PHP
Java
Ruby
Coming Soon
Want to add a language?
DeBugBuddy is open source. Contribute new patterns or add support for your favorite language.
Contribute on GitHubBuilding the future of debugging
Our journey to v1.0.0 — with new languages, integrations, and features every release.
Language Expansion & AI
- TypeScript, C, and PHP support
- AI provider integration
- Enhanced pattern matching
Prediction & GitHub
- Error prediction engine
- Custom pattern training
- GitHub issue integration
Java, Ruby & Grok
- Java and Ruby language support
- ML prediction optimization
- Basic error analytics in CLI
- Grok as AI provider
Go, Rust & IDE Integration
- Go and Rust language support
- VS Code extension
- Multi-file project scanning
- Mistral AI provider
Analytics Dashboard
- Web-based analytics dashboard
- Swift language support
- Export/import patterns
- Performance benchmarks
Team Collaboration
- Kotlin and C# support
- Slack bot integration
- Interactive charts
- Shareable reports
Discord & Cloud
- Discord bot integration
- Cloud sync (opt-in)
- Auto-suggest fixes from history
- User authentication for dashboard
Scale & Polish
- Scala and Elixir support
- Full integration testing
- Sub-1s startup time
- User feedback system
Production Ready
- 12+ language support
- Full-featured dashboard
- Slack & Discord bots
- Enterprise features
Q stands for quarter: Q1 (Jan-Mar), Q2 (Apr-Jun), Q3 (Jul-Sep), Q4 (Oct-Dec)
Frequently asked questions
Everything you need to know about DeBugBuddy.
Yes, absolutely. DeBugBuddy runs locally by default. Your code, error messages, and debugging history never leave your machine unless you explicitly opt into AI mode. Even with AI enabled, only the specific error context is sent to your chosen provider.
For debugging, yes! Instead of copying error messages, searching, reading through multiple answers, and adapting solutions — you get instant, context-aware explanations right in your terminal. It's like having a debugging expert on call.
Absolutely. You can create custom JSON pattern files and load them with `dbug train --patterns custom.json`. These are merged with the built-in patterns. You can also train ML models on your error history for personalized predictions.
DeBugBuddy uses 150+ hand-crafted patterns plus optional ML prediction. Pattern matching catches common issues with high accuracy. ML prediction learns from your coding patterns over time. Accuracy improves as you use it more.
DeBugBuddy requires Python 3.8 or higher. It's tested on Python 3.8, 3.9, 3.10, 3.11, and 3.12. The TUI interface uses Textual, which has excellent cross-platform support.
Yes! The core functionality works completely offline. Pattern matching, error explanations, prediction, and history all work without internet. Only AI-enhanced explanations and GitHub search require connectivity.
We'd love contributions! Check out the patterns/ directory in our GitHub repo for examples. Each language has a JSON file with error patterns. Submit a PR with your patterns, and we'll review and merge. See CONTRIBUTING.md for guidelines.
Not yet, but it's on our roadmap for v0.5.0! We're planning a VS Code extension first, with other editors to follow. In the meantime, the TUI provides a great integrated experience.
Still have questions?
Ask in Discussions