DebugChronicle

Stop guessing where bugs came from. Track the timeline, find the root cause, and deploy with confidence.

DebugChronicle is an offline debugging assistant for VS Code. It automatically captures file edits, compiler/linter diagnostics, terminal outputs, and runtime exceptions straight from the active debugger, organizing them into an interactive chronological timeline. It then uses a deterministic multi-factor scorer to trace which code change caused the crash—fully locally, with no cloud calls, accounts, or telemetry required.

Why DebugChronicle?

Traditional error trackers tell you that something broke. DebugChronicle reconstructs the story of how it broke, pointing directly to the root cause:

• 🔌 Zero-Config Runtime Exception Capturing: Automatically hooks into the VS Code Debugger (via Debug Adapter Protocol) to record runtime exceptions in Node.js, Python, Go, or any other DAP-compliant language the instant they occur.
• 🩺 Problems & Diagnostics Sniffer: Listens to VS Code's diagnostic language services to capture typescript errors, linter warnings, and compilation issues the moment they are introduced into your workspace.
• 🐚 Integrated Terminal Error Scraper: Tracks command-line builds and script runs, extracting errors and stack traces.
• 🎯 Deterministic Root-Cause Scorer: Ranks recent code modifications and environment updates using a weighted model that measures time proximity, stack-trace relevance, edit frequency, and Git blame recency.
• 📊 Status-Bar Health Pill: A customizable project-health indicator displaying your current workspace health score and number of open incidents at a glance.
• 📄 Advanced Shareable Reports: Export a beautiful, action-oriented Markdown incident report for a single error, or download complete session timelines as Markdown (.md) or Microsoft Word (.docx) files for PR code reviews and post-mortems.
• 🔒 100% Local & Privacy-First: All state, sessions, and timelines reside in the .debugchronicle/ directory in your workspace. Absolutely no network requests are made.

Detailed Features

1. Zero-Config Debugger Exception Hooking

When your code crashes during an active debugging session, DebugChronicle intercepts the uncaught exception, parses its stack frames, and matches them to your recent workspace file modifications. No manual logging required.

2. Export and Share Session Logs

Export single incident summaries directly, or use the Download Session Report button in the Webview UI to export chronological work-session logs in Markdown or Microsoft Word format, complete with hotspots, file edits, and git change statistics.

3. Interactive Webview Control Panel

Launch the sidebar timeline view to search and filter events, replay your edits step-by-step, examine hotspots, and view a dependency graph of how changes propagated into a failure.

Technical Specifications

How the Scorer Works

When an error is captured, DebugChronicle evaluates all preceding actions within a configurable time window (defaulting to 5 minutes). Every potential root cause is evaluated against a weighted model:

The scores are normalized into a 0–100% confidence level and presented in the Webview as the most likely suspects.

Quick Start

Installation

From Visual Studio Marketplace (Recommended)

1. Open VS Code.
2. Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X).
3. Search for DebugChronicle.
4. Click Install.

From VSIX (Manual Release)

Download the .vsix file from the releases page and install it via the terminal:

code --install-extension debugchronicle-0.2.2.vsix

Usage

1. Open a workspace and start writing code.
2. Run your code through the standard VS Code debugger, the integrated terminal, or simply observe lint/problems alerts.
3. Open the DebugChronicle view from the Activity Bar icon or by pressing Ctrl+Shift+D T (Cmd+Shift+D T on macOS) to view your timeline and analysis cards.

Extension Commands

All commands can be executed from the VS Code Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Extension Settings

You can customize the extension behavior in your VS Code User or Workspace settings (settings.json):

Local Development

To run the extension locally or contribute changes:

1. Clone the repository and install dependencies:

   git clone https://github.com/sakshicnimje7/DebugChronicle.git
   cd DebugChronicle
   npm install
   

2. Build the extension:

   npm run compile   # Incremental build for development
   npm run package   # Production bundle with minification and sourcemaps
   

3. Run the extension:
   • Open the directory in VS Code.
   • Press F5 to open the Extension Development Host.
4. Run tests:

   npm test                  # Runs unit tests (59 assertions)
   npm run test:integration  # Runs integration smoke-tests inside a mock VS Code instance
   npm run lint              # ESLint source code verification
   

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

• ARCHITECTURE.md — Detailed service layout and communication layers.
• DEVELOPMENT.md — Setup and test suite overview.
• CHANGELOG.md — History of features, fixes, and release versions.
• PUBLISHING.md — Guide on publishing VSIX artifacts.