Jessica

A desktop voice assistant that actually lives on your desktop.

Because talking to a browser tab never felt right.

---

The Problem

Voice assistants either live in a walled-garden smart speaker that can't touch your PC, or they're a chat window you still have to type into. Neither one listens for a clap, opens your editor, reads a reminder aloud, or holds a real conversation without a wake word gimmick bolted on top.

That's not an assistant. That's a search bar with a microphone icon.

---

The Solution

python jessica.py

Done. A frameless window opens, the tray icon comes alive, and Jessica is listening.

Jessica is a standalone Windows desktop app — a pywebview shell around a React UI, backed by a Python voice runtime that handles capture, transcription, reasoning, and speech in one continuous loop. No browser tab. No cloud dashboard. It runs where you work.

Note

Free to run. OpenRouter's free models and ElevenLabs' free tier voices are enough to use every feature out of the box — no subscription required. Paid models and voices are supported too, purely as an optional upgrade for users who want a premium experience.

---

---

What's Supported

✅ Voice Runtime

• Clap detection — double-clap wake trigger, tunable spike ratio and cooldown
• Conversational STT → LLM → TTS loop — ElevenLabs Scribe or local faster-whisper for transcription, OpenRouter for reasoning, ElevenLabs for speech
• Pause / wake phrases — "Jessica, hold on." and "Jessica, wake up." mid-session
• Exit phrases — natural goodbyes end the session without a forced command
• Welcome sequence — cached greeting audio, optional song-then-greet flow

✅ Desktop Shell

• Frameless pywebview window with custom title bar, tray icon, and single-instance lock
• Launch on Windows startup, close-to-tray, start-minimized — all toggleable
• Text chat — streaming markdown, session history, model picker with reasoning effort
• Reminders — natural-language scheduling, polling, TTS playback on fire
• Settings — API keys, audio devices, voice tuning, appearance, all persisted locally

⚠️ Scope

Windows-only by design (pywebview, tray, HKCU startup registration). No server component — everything runs locally against your own OpenRouter and ElevenLabs keys.

---

Installation

git clone https://github.com/immapolar/Jessica.git
cd Jessica
python -m pip install -r requirements.txt

cd ui
npm install
npm run build   # builds the React UI into ui/dist

Prerequisites: Python 3.12, Node.js (for the UI build), a free OpenRouter API key, and a free ElevenLabs API key and voice ID. No paid plan on either service is required.

---

Usage

python jessica.py             # production — loads the built UI
python jessica.py --dev       # development — loads Vite dev server at :5173
python jessica.py --minimized # start hidden in the tray

On first launch with no %USERPROFILE%\.jessica\, an onboarding overlay collects your API keys and voice ID. A legacy .env next to jessica.py is imported automatically.

---

Project Structure

Jessica/
├── jessica.py              # Entry point
├── jessica/
│   ├── agent/              # Orchestrator, pipeline, phrase matching
│   ├── audio/               # Capture, playback, clap & voice detection
│   ├── chat/                 # Chat runtime, sessions, streaming client
│   ├── config/                # Settings schema, secrets, runtime
│   ├── desktop/                 # pywebview app, tray, window, startup
│   ├── integrations/            # ElevenLabs SDK/API/transport
│   ├── llm/                      # OpenRouter client
│   ├── reminders/                 # Parser, scheduler, store, GUI
│   ├── session/                    # History & state
│   ├── stt/                         # ElevenLabs & faster-whisper backends
│   └── tts/                          # ElevenLabs speech synthesis
├── ui/
│   ├── src/                # React + TypeScript source
│   ├── public/assets/      # Brand imagery
│   └── dist/               # Built UI (bundled into the EXE)
└── requirements.txt

---

License

MIT © 2026 Polaris

---

_{An assistant that lives on your machine, not in your browser.}