Your terminal’s debugging companion

Stop Googling. Understand your errors.

Install • Quick Start • Docs

Overview and Purpose

DeBugBuddy is an open-source, Python-based CLI tool designed as a “terminal’s debugging companion” to provide instant, context-aware explanations for error messages without requiring users to search external resources like StackOverflow or documentation. DeBugBuddy focuses on local processing for privacy (unless AI mode is opted in) and supports a wide range of error types across multiple programming languages. DeBugBuddy also emphasizes ease of use for developers, reducing context-switching during debugging by integrating features like error prediction, file watching, and history tracking directly in the terminal.

Installation

pip install debugbuddy-cli

Documentation

All Commands

dbug explain     Explain an error message
dbug predict     Predict errors in a file
dbug watch       Watch files for errors
dbug history     View error history
dbug train       Train custom patterns or ML models
dbug search      Search error patterns
dbug config      Manage configuration
dbug github      GitHub integration

Supported Error Types

Python (60+ built-in exceptions & common issues)

• ArithmeticError • AssertionError • AttributeError • BlockingIOError
• BrokenPipeError • BufferError • ChildProcessError • ConnectionAbortedError
• ConnectionError • ConnectionRefusedError • ConnectionResetError
• EOFError • FileExistsError • FileNotFoundError • FloatingPointError
• ImportError • IndentationError • IndexError • InterruptedError
• IsADirectoryError • KeyError • KeyboardInterrupt • MemoryError
• ModuleNotFoundError • NameError • NotADirectoryError • NotImplementedError
• OSError • OverflowError • PermissionError • ProcessLookupError
• RecursionError • ReferenceError • RuntimeError • StopIteration
• SyntaxError • TabError • TimeoutError • TypeError
• UnboundLocalError • UnicodeDecodeError • UnicodeEncodeError
• ValueError • ZeroDivisionError • and many more warnings (DeprecationWarning, FutureWarning, etc.)

JavaScript / Node.js (All 7 built-in errors)

• AggregateError • EvalError • InternalError • RangeError
• ReferenceError • SyntaxError • TypeError • URIError

TypeScript (Core compiler errors & type issues)

• Type Error (TS2345: not assignable) • Declaration Error (TS2304: cannot find name, TS1008: expected)
• Module Resolution (TS2307: cannot find module) • Interface Error (TS2322/2324: missing property)
• Generic Type Error (TS2322: constraint violated) • Union Type Error (TS2322/2345: not assignable)
• Async Type Error (TS2322: promise mismatch) • Syntax Error (TS1003/1005: invalid token)
• Null/Undefined Error (TS2532/2533: strict null checks) • Import/Export Error (TS2305/1192: not found)

C / C++ (Compiler, linker & runtime)

• Syntax Error • Undefined Reference / Linker Error
• Segmentation Fault (segfault) • Null Pointer Dereference
• Type Mismatch • Array Bounds Error • Memory Leak
• Format String Mismatch • Division by Zero • Uninitialized Variable
• Include Error • Undefined Behavior

PHP (All 16+ error levels)

• Parse Error (E_PARSE) • Fatal Error (E_ERROR) • Warning (E_WARNING)
• Notice (E_NOTICE) • Deprecated (E_DEPRECATED) • Type Error (E_RECOVERABLE_ERROR)
• Division by Zero • Out of Memory • Strict (E_STRICT) • Core Error (E_CORE_ERROR)
• Core Warning (E_CORE_WARNING) • Compile Error (E_COMPILE_ERROR)
• Compile Warning (E_COMPILE_WARNING) • User Error (E_USER_ERROR)
• User Warning (E_USER_WARNING) • User Notice (E_USER_NOTICE) • User Deprecated (E_USER_DEPRECATED)

Universal / Common Errors (cross-language)

• Compilation Error • Logic Error • Runtime Error • Linkage Error
• Segmentation Fault • Network Error • Permission Error
• Timeout Error • Memory Error • Database Error
• API Key Error • SSL/Certificate Error • Input/Validation Error
• Off-by-One Error • Infinite Loop

Total supported error patterns: 150+ and growing (expanded via official docs & common patterns)

Contributing

Contribute in any way you want. You can report bugs, add patterns, write docs, or extend support for other languages. See CONTRIBUTING.md for the full guide.

Roadmap

v0.2.0 ✅

• Typescript, C and PHP Language Support
• AI support

v0.3.0 ✅

• Error prediction
• Custom pattern training
• GitHub integration

v0.4.0 (Q1 2026) ❌

• Java and Ruby Language Support
• ML prediction optimization for faster inference (e.g., model quantization, caching improvements).
• Introduce basic error analytics in CLI (e.g., stats on frequent errors from history).
• Introduce Grok as an AI Provider for the AI Mode.
• Full test coverage for new languages; refactor pattern manager for easier additions.

v0.5.0 (Q2 2026) ❌

• Go and Rust Language Support
• Implement IDE integrations (e.g., VS Code extension for seamless CLI calls).
• Improve custom training with user-friendly wizards and example datasets.
• Add multi-file/project scanning for prediction/watch.
• Security audit and fixes (e.g., safe error message parsing to prevent injection).

v0.6.0 (Q3 2026) ❌

• Introduce a basic web-based error analytics dashboard (e.g., using Flask/Dash; local server mode) for visualizing history, patterns, and predictions.
• Swift Language Support
• Enable export/import of patterns and history (e.g., JSON/CSV).
• Introduce performance benchmarks and optimizations for large projects.
• Community features: Template for contributing new language patterns.

v0.7.0 (Q3 2026) ❌

• Kotlin and C# Language Support
• Implement Slack bot for error explanations/predictions (e.g., slash commands to query from chat).
• Enhance dashboard with interactive charts (e.g., error frequency over time, language breakdowns).
• Add collaborative mode (e.g., share prediction reports via links).
• Extensive documentation updates, including API reference for extensions.

v0.8.0 (Q4 2026) ❌

• Implement Discord bot with similar features to Slack (e.g., error queries, notifications).
• Dashboard enhancements: User authentication, cloud sync option (opt-in for privacy).
• Introduce advanced ML features (e.g., auto-suggest fixes based on history).

v0.9.0 (Q4 2026) ❌

• Scala and Elixir Language Support
• Full integration testing for dashboard.
• Performance profiling and optimizations (e.g., reduce startup time <1s).
• User feedback loop: Add in-app surveys or GitHub issue templates.

v1.0.0 (Q1 2027) - Stable Release ❌

• Official support for 12+ languages.
• Fully featured error analytics dashboard (local/web, with visualizations and exports).
• Slack and Discord bots support for real-time debugging assistance.

Note

The Q in brackets stands for Quarter. This is a common convention in project roadmaps, product planning, and software release timelines: • Q1 → First quarter of the year (January–March) • Q2 → Second quarter (April–June) • Q3 → Third quarter (July–September) • Q4 → Fourth quarter (October–December) I used it to indicate approximate target timeframes for each version’s release, starting from early 2026.

FAQ

Q: Is my code private?
A: Yes. Everything stays local unless you opt into AI mode.

Q: Does it replace StackOverflow?
A: For debugging, yes. You stop switching tools.

Q: Can I add custom patterns?
A: Yes. Edit the JSON files in ./patterns.

Support

If DeBugBuddy helps you, star the GitHub repo. Stars help other developers discover the tool.

Made with ❤️ by DevArqf

Stop Googling. Understand your errors.