🌑 Shadow AI — Invisible Interview Copilot

Shadow AI is a macOS desktop overlay that listens to your system audio in real time, transcribes it using Groq Whisper, and generates AI-powered responses — all in a window invisible to screen sharing and recording software.

Built for technical interviews, coding challenges, and meetings — your interviewer sees nothing.

---

✨ Features

• 🎙️ Real-time system audio capture — captures everything playing on your Mac (Zoom calls, browser audio, etc.)
• 🤫 Invisible to screen sharing — the overlay is hidden from any screen recording or sharing tool
• 🧠 Context-aware AI responses — remembers conversation history and gives structured, interview-quality answers
• 💻 8 specialized session modes — SDE, Data Science, PM, Business, Data Analyst, Meeting, General, and Custom
• ⌨️ Manual question input — type questions directly when you don't want to rely on audio
• 📸 Screen capture mode — AI can see and analyze what's on your screen
• 💾 Code detail windows — dedicated floating windows for code snippets with syntax highlighting
• 📊 Code compare view — side-by-side naive vs optimal solution viewer
• 📄 Document upload — upload PDFs and DOCX files as context for the AI
• 🔄 Auto-fallback — switches to Cerebras when Groq hits rate limits (seamless, no interruption)
• 📉 Token-optimized — smart conversation history compression saves ~40-50% in API costs

---

🖥️ Requirements

Requirement	Version
macOS	12 Monterey or later
Node.js	18+
npm	8+
Groq API Key	Free at console.groq.com
Cerebras API Key (optional)	Free at cloud.cerebras.ai

Windows/Linux are not supported. The app uses macOS-specific APIs for window invisibility, system audio capture, and screen recording permissions.

---

🚀 Installation & Setup

Step 1 — Clone the repository

git clone https://github.com/YOUR_USERNAME/ShadowChatbot.git
cd ShadowChatbot

Step 2 — Install dependencies

npm install

Step 3 — Add your API keys

Open services/groq.js in any text editor:

nano services/groq.js
# or
code services/groq.js

Find the constructor (around line 6) and replace the placeholder values with your own keys:

class GroqService {
    constructor(apiKey) {
        // ✅ Replace with your Groq API key
        this.apiKey = 'YOUR_GROQ_API_KEY_HERE';
        
        // ✅ Replace with your Cerebras API key (used as fallback when Groq rate-limits)
        this.cerebrasApiKey = 'YOUR_CEREBRAS_API_KEY_HERE';
        
        // ... rest of the constructor
    }
}

Important: Never commit your real API keys to GitHub. See the API Key Security section below.

Step 4 — Grant macOS Screen Recording permission

1. Open System Settings → Privacy & Security → Screen Recording
2. Enable the toggle for Electron (or your app's name)
3. If it doesn't appear, run the app once (npm start) and it will prompt for access

Step 5 — Run the app

npm start

---

🔑 Getting Your API Keys

Groq API Key (Required)

Groq powers both speech-to-text (Whisper large-v3-turbo) and the LLM (Llama 3.3 70B). Groq's free tier is generous:

1. Go to console.groq.com
2. Sign up or log in
3. Click API Keys in the sidebar → Create API Key
4. Copy the key (starts with gsk_...)
5. Paste it into services/groq.js as shown above

Cerebras API Key (Optional — Fallback)

Cerebras is used as an automatic fallback when Groq hits rate limits. Highly recommended for sustained usage:

1. Go to cloud.cerebras.ai
2. Sign up or log in
3. Click your profile → API Keys → Create new API key
4. Copy the key (starts with csk_...)
5. Paste it into services/groq.js as this.cerebrasApiKey

If you don't have a Cerebras key, just leave the field blank — the app will only use Groq. Set this.cerebrasApiKey = ''; to disable the fallback.

---

🔐 API Key Security

⚠️ NEVER commit your API keys to a public repository.

To keep your keys safe, use a .env file pattern:

Option A — Environment variables (recommended)

Create a .env file in the project root:

GROQ_API_KEY=gsk_your_key_here
CEREBRAS_API_KEY=csk_your_key_here

Add .env to .gitignore:

echo ".env" >> .gitignore

Then in services/groq.js, read from environment:

// In Electron renderer, use ipcMain to pass env vars from main process
// Or use a local config file pattern
this.apiKey = process.env.GROQ_API_KEY || 'fallback';

Option B — Local config file

Create config.local.js (add to .gitignore):

module.exports = {
    groqApiKey: 'gsk_your_key_here',
    cerebrasApiKey: 'csk_your_key_here'
};

Import it in services/groq.js:

const config = require('../config.local.js');
this.apiKey = config.groqApiKey;

---

🎮 Usage

Starting a Session

1. Launch the app with npm start
2. On the home screen, choose your session mode (SDE, DS, PM, etc.)
3. Optionally add a briefing — paste your resume, job description, or any context you want the AI to know
4. Click Launch Overlay

Keyboard Shortcuts

Shortcut	Action
Cmd + Shift + L	Toggle audio listening on/off
Cmd + Shift + H	Show/hide the overlay
Cmd + Q	Quit the app

During an Interview

• Press Cmd+Shift+L to start listening — the overlay picks up system audio automatically
• Talk or let the interviewer talk — transcripts appear in the left pane
• After 5 seconds of silence, the AI generates a response in the right pane
• Use the manual input box at the bottom to type questions directly
• Click any AI response to copy it or view code in a detail window

---

🧩 Session Modes

Mode	Best For
💻 SDE	LeetCode, system design, FAANG-style coding interviews
📊 Data Scientist	ML concepts, SQL, statistics, A/B testing, case studies
🎯 Product Manager	Product sense, strategy, metrics, estimation, roadmaps
📈 Business & Marketing	Consulting cases, marketing analytics, financial analysis
🔍 Data Analyst	SQL queries, Excel, Tableau/Power BI, dashboards
🤝 Meeting Assistant	Live note-taking, action items, Q&A during meetings
✨ General	All-purpose assistant for anything
⚙️ Custom	Write your own system prompt for any use case

---

🏗️ Project Architecture

ShadowChatbot/
├── main.js                 # Electron main process — windows, IPC, permissions
├── preload.js              # Secure bridge between main and renderer
├── renderer.js             # Core UI logic, audio pipeline, AI response handling
├── index.html              # Overlay window HTML
├── home.html               # Setup/briefing screen HTML
├── styles.css              # Overlay styles
├── home-styles.css         # Home screen styles
├── home-renderer.js        # Home screen logic
├── code-detail.html        # Floating code window
├── code-compare.html       # Side-by-side code compare window
├── code-viewer.html        # Code snippet list window
└── services/
    ├── groq.js             # Groq + Cerebras API wrapper (STT + LLM)
    ├── audio.js            # System audio capture + WAV encoding
    ├── prompts.js          # Session mode system prompts
    ├── context.js          # Screen capture + context extraction
    └── code-extractor.js   # Code snippet parser from AI responses

How Audio Capture Works

macOS System Audio
      ↓
desktopCapturer (Electron)
      ↓
getUserMedia (audio + video stream)
      ↓ (video track kept alive to maintain capture session)
MediaStream (audio-only) → MediaRecorder (timeslice: 3s)
      ↓
ondataavailable → WebM chunks
      ↓
AudioContext.decodeAudioData → OfflineAudioContext resample to 16kHz
      ↓
WAV blob → Groq Whisper API → Transcript text
      ↓
Transcript buffer (5s silence timeout) → Groq Llama 3.3 70B → AI Response

---

🛠️ Troubleshooting

Audio capture not working

1. Check Screen Recording permission — System Settings → Privacy & Security → Screen Recording → Electron ✅
2. Fully quit and restart after granting permission (Cmd+Q, not just closing the window)
3. Make sure audio is actually playing — the app captures system audio, so something must be playing (YouTube, Zoom, etc.)
4. Check the DevTools console (Cmd+Option+I) for [Audio] log messages

AI not responding

1. Check your Groq API key is set correctly in services/groq.js
2. Check the console for API error messages (401 = wrong key, 429 = rate limit)
3. If you see rate limit errors, add a Cerebras API key as a fallback

"Autofill.enable failed" errors in terminal

These are harmless DevTools protocol warnings from Electron — ignore them. They don't affect functionality.

App not invisible to screen recording

Ensure you are running the app with npm start (not packaged). The setContentProtection(true) flag is set for all windows, which hides them from screen capture on macOS.

---

🤝 Contributing

Pull requests are welcome! For major changes, open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

---

📄 License

MIT License — see LICENSE for details.

---

⚠️ Disclaimer

Shadow AI is intended for personal productivity and learning. Use responsibly and in accordance with the terms of service of any platform you use it with. The authors are not responsible for misuse.