How to Enable and Use DevTools for Debugging the chat-mcp Electron Application

You can enable DevTools in the chat-mcp Electron application by either uncommenting mainWindow.webContents.openDevTools() in src/main/main.ts or importing the electron-debug package to toggle debugging with Ctrl+Shift+I (Windows/Linux) or Cmd+Alt+I (macOS).

The chat-mcp repository provides an Electron-based desktop client where UI rendering occurs in a BrowserWindow managed by the main process. Enabling DevTools for debugging the Electron application is essential for inspecting HTML elements, monitoring console output, and diagnosing IPC communication between processes. The following methods leverage the actual source code implementation found in the ai-ql/chat-mcp codebase.

Enable DevTools Programmatically in main.ts

The most direct approach involves modifying the main process entry point to open DevTools automatically on launch. In src/main/main.ts, the createWindow() function contains a commented line (lines 123-124) that controls this behavior.

Locate the following code block within the createWindow() function:

// src/main/main.ts
mainWindow.loadFile(indexPath);

// Uncomment to open DevTools automatically on each launch
mainWindow.webContents.openDevTools();

Uncommenting mainWindow.webContents.openDevTools() forces the Chromium DevTools panel to appear immediately after the window loads src/renderer/index.html. This method requires rebuilding the application using npm start, which automatically compiles TypeScript sources from src/ to dist/ before launching Electron with dist/main/main.js.

Toggle DevTools with electron-debug Shortcuts

For debugging without modifying source code between sessions, integrate the electron-debug package already listed in devDependencies. This method registers global keyboard shortcuts that toggle DevTools visibility at runtime without rebuilding after the initial setup.

Add the following import at the top of src/main/main.ts:

// src/main/main.ts
import 'electron-debug';

// ...rest of the file unchanged

After rebuilding with npm start, press Ctrl+Shift+I on Windows/Linux or Cmd+Alt+I on macOS to open or close DevTools instantly. This approach also exposes window.__devtron for additional debugging capabilities and does not affect production builds since electron-debug is excluded from packaged applications.

Configure Remote Debugging Port

Advanced debugging scenarios require attaching external tools such as VS Code or Chrome DevTools to a running Electron instance. Launch the application with the --remote-debugging-port flag to expose a debugging endpoint accessible via HTTP.

Execute the following command:

npm start -- --remote-debugging-port=9222

This flag instructs the Chromium engine to expose debugging information at http://localhost:9222, allowing external debuggers to connect to the renderer process via the Chrome DevTools Protocol while the application runs.

Architecture and Implementation Details

The main process runs in src/main/main.ts and creates a BrowserWindow with specific security configurations that affect debugging scope:

const mainWindow = new BrowserWindow({
  width: 1920,
  height: 1080,
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    preload: preloadPath
  }
});

The webContents object of this window provides the openDevTools() method used for debugging. Because contextIsolation is enabled and nodeIntegration is disabled, DevTools inspection focuses on the renderer context loaded from src/renderer/index.html rather than Node.js internals, ensuring secure separation between main and renderer processes.

Summary

• Programmatic method: Uncomment mainWindow.webContents.openDevTools() in src/main/main.ts for automatic DevTools opening on every launch.
• Keyboard shortcut method: Import electron-debug in the main entry file to enable Ctrl+Shift+I / Cmd+Alt+I toggling without subsequent code changes.
• Remote debugging: Use --remote-debugging-port=9222 when launching to attach external debugging tools via the Chrome DevTools Protocol.
• Rebuild requirement: Any modification to src/main/main.ts requires running npm start to recompile TypeScript from src/ to dist/ before changes take effect.

Frequently Asked Questions

Where is the DevTools configuration located in chat-mcp?

The configuration resides in src/main/main.ts within the createWindow() function. The specific line mainWindow.webContents.openDevTools() appears commented out immediately after mainWindow.loadFile(indexPath), allowing developers to opt-in to automatic DevTools opening by uncommenting it.

Does enabling DevTools affect production builds?

No. When using the electron-debug method, the package is listed under devDependencies in package.json, ensuring it is excluded from production builds. The programmatic method using openDevTools() should be commented out or wrapped in environment checks before packaging to prevent end-users from seeing the developer tools.

How do I debug the main process versus the renderer process?

The methods described above debug the renderer process (the UI window). To debug the main process itself (Node.js context in src/main/main.ts), you must use the --inspect flag when launching Electron or configure VS Code with a Node.js debugger attachment, as the Chromium DevTools only inspect the renderer's web contents.

What keyboard shortcuts toggle DevTools when using electron-debug?

When import 'electron-debug' is active in src/main/main.ts, the registered shortcuts are Ctrl+Shift+I on Windows and Linux, or Cmd+Alt+I on macOS. These shortcuts toggle the visibility of the DevTools panel without requiring application restarts or source modifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}