⬡ AI Debug Lens

Zero-dependency Node.js utility that intercepts console.error at runtime, captures the surrounding source-code snippet, and serves a live dashboard with one-click AI-prompt generation.

The Problem

You hit an error in your Node app. You copy the message into ChatGPT or Claude. You paste the stack trace. Then you realise the AI still needs to see the actual lines of code around the crash — so you go back, find the file, scroll to the right line, copy the snippet, and paste it again.

AI Debug Lens eliminates that round-trip entirely.

How It Works

Your app throws an error
        │
        ▼
console.error is intercepted
        │
        ├─► Walks the call stack to find the exact source file + line number
        ├─► Reads that file and extracts a ±2-line context window
        └─► Stores the enriched entry in an in-memory vault
                │
                ▼
        http://localhost:8080
        Live dashboard — auto-refreshes every 3 s
        Shows every log/error with its code snippet
        "Copy for AI" button assembles a ready-to-paste prompt

No build step. No external dependencies. No config files. Just require and go.

Installation

# from npm (once published)
npm install ai-debug-lens

# or copy index.js directly into your project

Quick Start

// At the very top of your entry file (e.g. app.js)
const { startDashboard } = require('ai-debug-lens');
startDashboard(); // boots the dashboard on http://localhost:8080

// The rest of your app is completely unchanged.
// Every console.log and console.error will now be intercepted.

console.log('Server starting…');
console.error(new Error('Something went wrong'));

Open http://localhost:8080 in your browser. You'll see every intercepted entry with:

• The error message
• The file path and line number
• A ±2-line source-code snippet
• A ✦ Copy context for AI button

Dashboard Preview

⬡ AI Debug Lens                          auto-refreshes every 3 s
────────────────────────────────────────────────────────────────────
Total 3   Errors 1   Logs 2

┌─────────────────────────────────────────────────────────────────┐
│ ERROR                                    2025-06-01T14:22:03Z   │
│ Error: Cannot read properties of undefined (reading 'id')       │
│                                                                 │
│ source context — /app/routes/user.js:42                         │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │  40 │   const users = await db.getUsers();                  │ │
│ │  41 │   const names = users.map(u => {                      │ │
│ │  42 │     return u.profile.id;   // ← error here            │ │
│ │  43 │   });                                                  │ │
│ │  44 │   res.json(names);                                     │ │
│ └─────────────────────────────────────────────────────────────┘ │
│  [✦ Copy context for AI]                                        │
└─────────────────────────────────────────────────────────────────┘

Clicking Copy context for AI puts this on your clipboard — ready to paste:

I got this error:
Error: Cannot read properties of undefined (reading 'id')

Code context — /app/routes/user.js (line 42):

  40 │   const users = await db.getUsers();
  41 │   const names = users.map(u => {
  42 │     return u.profile.id;
  43 │   });
  44 │   res.json(names);

How do I fix this?

API

startDashboard(port?)

Starts the live dashboard HTTP server. Calling this more than once returns the existing server — no duplicate ports.

| Parameter | Type | Default | Description | |-----------|----------|---------|---------------------------------| | port | number | 8080 | Port to bind the HTTP server to |

Returns: http.Server

const { startDashboard } = require('ai-debug-lens');

const server = startDashboard(3001);

// Shut it down gracefully when needed
server.close();

getLogs()

Returns a shallow copy of the in-memory log vault.

Returns: LogEntry[]

const { getLogs } = require('ai-debug-lens');

const entries = getLogs();

entries.forEach(entry => {
  console.log(entry.type);       // 'log' | 'error'
  console.log(entry.timestamp);  // ISO-8601 string
  console.log(entry.messages);   // original arguments
  console.log(entry.context);    // { filePath, lineNum, snippet } | undefined
});

LogEntry shape

{
  type:      'log' | 'error';
  timestamp: string;           // ISO-8601
  messages:  unknown[];        // original console arguments
  context?: {                  // present on errors only
    filePath: string;          // absolute path to source file
    lineNum:  number;          // 1-based line number
    snippet:  string;          // 5-line window of source code
  };
}

Integration Examples

Express

const express = require('express');
const { startDashboard } = require('ai-debug-lens');

const app = express();
startDashboard(); // dashboard on :8080

app.get('/', (req, res) => {
  res.send('Hello World');
});

app.listen(3000, () => console.log('API on :3000'));

Exporting logs as JSON (e.g. for CI pipelines)

const { getLogs } = require('ai-debug-lens');

process.on('exit', () => {
  const fs = require('fs');
  fs.writeFileSync('debug-report.json', JSON.stringify(getLogs(), null, 2));
});

How Console Patching Works

AI Debug Lens replaces console.log and console.error with thin wrappers before your application code runs. The originals are captured via .bind() first, so they are immune to further patching.

console.error (patched)
    │
    ├─► getErrorContext()
    │       │
    │       ├─► new Error().stack  ← reads the live call stack
    │       ├─► parses frame [3]   ← the actual caller in your code
    │       ├─► fs.readFileSync()  ← reads your source file
    │       └─► returns { filePath, lineNum, snippet }
    │
    ├─► pushes enriched entry to logVault
    ├─► emits a diagnostic hint to stdout
    └─► calls original console.error  ← nothing is swallowed

The dashboard is entirely independent — it reads from logVault on every HTTP request, so it always reflects the latest state without any sockets or polling from the client side.

Security Notes

• Development use only. The dashboard is an unauthenticated HTTP server. Do not run it in production or expose it to the public internet.
• All strings are HTML-escaped before being injected into the dashboard, preventing XSS from error messages or file paths that contain HTML characters.

Requirements

• Node.js ≥ 14
• No npm dependencies

License

ISC © Habib Azzabou