shadow-debugger

shadow-debugger is a powerful tool designed for background error diagnosis in Python applications and web APIs, including frameworks like FastAPI, Flask, and Django. This utility operates seamlessly offline with Ollama or connects effortlessly with popular large language models (LLMs) such as Gemini, OpenAI, and Claude for enhanced debugging functionalities.

When an exception or HTTP 500 error occurs, shadow-debugger captures the relevant stack trace, redacts sensitive information from local variables and request data, and processes the context in a background thread. As a result, applications can return their normal responses immediately, while a comprehensive Markdown postmortem report is generated in the ./shadow_reports/ directory within seconds.

Key Features

• Efficient Error Reports: The generated reports contain detailed incident summaries, trigger conditions, proposed fixes, and preventive advice. For example, an error in an API’s order processing might lead to a ZeroDivisionError when discount items are improperly set.

  # Shadow Debugger Incident Report
  
  **Timestamp:** 2026-10-18T10:30:12.418290+00:00  
  **Exception:** `ZeroDivisionError`: division by zero  
  **Location:** `app/routes.py:42` in `checkout`  
  **Fingerprint:** `9f2a1c4b8e1032d1` (occurrences so far: 1)  
  
  ### 1. Root Cause Summary
  The `checkout()` function divides by a variable without validation, leading to potential errors.
  
  ### 2. Trigger Condition
  Calling `GET /checkout/1042?discount_items=0` resulting in an error due to division by zero.
  
  ### 3. Proposed Fix
  ```python
  unit_discount = 50 / discount_items if discount_items > 0 else 0.0
  

  4. Prevention Advice

  Implement parameter validation to prevent division by zero errors.

• Flexible Integration Options: Supports various cloud providers and local setups, allowing developers to select their preferred environment.

  import shadow_debugger
  shadow_debugger.init(provider="gemini", model="gemini-3.8-flash")
  

• Custom Provider Support: Enables the creation of tailored integrations with existing LLM backends, promoting versatility in error diagnosis approaches.

• Privacy-Centric Design: Ensures sensitive data is protected by replacing common secret terms with placeholders, safeguarding privacy during API calls.

Configuration and Customization

shadow-debugger offers a range of configurable options to optimize performance per project requirements, including provider specifications, output directories, and toggle settings for error reporting.

Community and Contribution

The project is open for community feedback and contributions, with a clear roadmap for future enhancements, such as integrating notification systems and extending support to additional LLM providers.

Visit the repository for more information and to participate in the project.