DEBUGGING.md

CHAD Debugging Guide

Current Issue: Loader Stuck on "Starting..."

What Was Fixed (Latest)

1. Splash Window Timing — Made splash window creation async and wait for full load
2. Server Wait Time — Added 2-second delay after server responds to let Open WebUI initialize
3. Progress Updates — Added safety checks and DOM ready event
4. Error Handling — Wrapped tool/IPC initialization in try-catch to prevent blocking

Changes Made to src/main.ts

// Before: Immediate splash creation
createSplash();

// After: Wait for splash to be fully ready
await createSplash(); // Now async, waits for renderer to be ready

// Before: Show main window immediately after server responds
await waitForServer(splash);
createMain();

// After: Wait 2 seconds after server responds + wait for render
await waitForServer(splash); // Now waits 2s after first response
createMain();
await main.loadURL(WEBUI_URL);
await new Promise(resolve => setTimeout(resolve, 500)); // Wait for render

How to Test

1. Rebuild CHAD:

   npm run build

2. Run with Console Output:

   npm start

3. Watch for Console Messages: You should see:

   Initializing CHAD tools...
   Tools initialized successfully
   Splash screen ready
   Server ready
   Main window created
   IPC handlers set up
   Main window loaded
   CHAD is ready!
   

4. Check for Errors: If you see warnings like:

   • "Warning: Failed to initialize tools" — Tools didn't load (non-critical)
   • "Warning: Failed to setup IPC" — IPC didn't initialize (non-critical for basic UI)
   • Any other errors will be shown in red

Debugging the Splash Screen

If the loader is still stuck, add DevTools to the splash window temporarily:

In src/main.ts, add after line 71:

splash.loadFile(path.join(__dirname, "loading.html"));
splash.webContents.openDevTools(); // ← Add this line temporarily

Then rebuild and run. The splash window will show DevTools where you can:

1. Check the Console tab for JavaScript errors
2. Look for window.api availability
3. See if IPC messages are being received

Common Issues

Issue 1: "window.api is not defined"

Cause: Preload script not loading

Fix:

1. Check that dist/preload.js exists
2. Verify preload: path.join(__dirname, "preload.js") in createSplash()
3. Rebuild: npm run build

Issue 2: No progress updates

Cause: IPC not working or splash not ready

Fix:

1. Check console for "Splash screen ready" message
2. Verify loading-progress IPC channel name matches in preload.ts
3. Check DevTools console in splash window

Issue 3: "OI" splash still shows

Cause: Server not fully initialized before loading URL

Current Fix: 2-second wait after server responds

If still happening: Increase wait time in waitForServer():

// Line ~36 in main.ts
setTimeout(() => {
  clearInterval(timer);
  resolve();
}, 3000); // ← Increase to 3 or 4 seconds

Issue 4: Everything stops after "Server ready"

Cause: Main window creation or URL loading failing

Fix:

1. Check if Open WebUI dev server is actually running on port 5173
2. Test manually: Open browser to http://localhost:5173
3. Check open-webui/ folder has node_modules installed

Manual Server Test

Test if Open WebUI runs independently:

cd open-webui
npm run dev

Then open browser to http://localhost:5173

If this works but CHAD doesn't, the issue is in the Electron integration.

Check File Existence

Verify all required files are compiled:

# Should exist after build
dir dist\*.js
dir dist\loading.html

# Required:
# - dist/main.js
# - dist/preload.js
# - dist/ipc.js
# - dist/orchestrator.js
# - dist/loading.html
# - dist/ai/cluster.js
# - dist/tools/*.js

IPC Test

Once the main window loads (even if splash is stuck), open DevTools (F12) and test:

// Should not be undefined
console.log(window.chad);

// Should not throw error
window.chad.health().then(console.log);

If window.chad is undefined:

• Preload script didn't run in main window
• Check main window has preload path set

Build Issues

If build fails:

1. Check for TypeScript errors:

   npx tsc -p tsconfig.json --noEmit

2. Clean build:

   npm run clean
   npm run build

3. Check Node.js version:

   node --version
   # Should be 18 or higher

Nuclear Option: Minimal Test

Create test-minimal.js in root:

const { app, BrowserWindow } = require('electron');
const path = require('path');

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'dist', 'preload.js'),
    }
  });
  
  win.loadFile(path.join(__dirname, 'dist', 'loading.html'));
  win.webContents.openDevTools();
  
  // Send test progress
  setInterval(() => {
    const percent = Math.floor(Math.random() * 100);
    win.webContents.send('loading-progress', { percent, eta: 5 });
  }, 500);
});

Run with: npx electron test-minimal.js

This tests ONLY the splash screen and IPC.

Expected Timeline

With the fixes:

1. 0s — Splash appears (CHAD logo, "Starting...")
2. 0-3s — Loading bar starts animating (0% → 90%)
3. 3-5s — Server ready, bar reaches 95%
4. 5-6s — Main window loading (hidden)
5. 6s — Bar reaches 100%, "Ready!"
6. 6.3s — Main window shows, splash closes

Total: ~6-7 seconds from start to Open WebUI visible

Still Stuck?

If the loader is still stuck on "Starting..." after these fixes:

1. Enable DevTools on splash (see above)
2. Check Console for errors
3. Verify window.api exists
4. Run minimal test (see above)
5. Share console output — Post the console messages to help diagnose

Next Steps After Fixing

Once the startup works:

1. Test window.chad API in main window
2. Verify Ollama is running and models loaded
3. Try a chat request
4. Set up Open WebUI integration

---

TL;DR for Current Issue:

Run these commands:

npm run build
npm start

Watch console output. If still stuck, enable DevTools on splash window to see browser console errors.