# Wivexx

A local, voice-first AI assistant for Windows, powered by Claude. Wivexx lives in
your system tray, listens for its wake word, and answers out loud — with a
web-tech "control room" window, a living animated dot, and a set of practical
skills (memory, calendar, file delivery, goals, hotkeys and more).

> Say **"Wivexx"** to wake it, then just talk.

---

## Requirements

- **Windows 10 or 11**
- **Python 3.10, 3.11 or 3.12** (64-bit) — install from
  [python.org](https://www.python.org/downloads/) and tick **"Add Python to PATH"**
  during setup. ⚠️ Avoid the very newest Python (3.13+) for now: a few optional
  voice extras don't ship prebuilt installers for it yet, so first-run install can
  fail. **3.12 is the safe pick.** (Wivexx still runs on 3.13 — it just skips those
  optional extras.)
- A **microphone** and **speakers/headphones**.
- An **Anthropic API key** — create one at [console.anthropic.com](https://console.anthropic.com/).

## Quick start

1. **Install Python** (see above) and confirm it works: open a terminal and run
   `python --version`.
2. **Add your API key.** Copy `.env.example` to a new file named `.env` and paste
   your key in:
   ```
   ANTHROPIC_API_KEY=sk-ant-...
   ```
   (Leave the Supabase lines blank to run fully locally.)
3. **First run.** Double-click **`start_wivexx.bat`** once — it installs the Python
   packages (from `requirements.txt`) and launches Wivexx in a console so you can
   see any setup messages.
4. **Everyday use.** After the first run, just double-click **`Wivexx.vbs`** — it
   starts silently in the background. (Want a Desktop icon? Double-click
   **`Create Desktop Shortcut.vbs`** once — see "Make a desktop shortcut" below.)
   Look for the dot in your system tray (bottom-right). Right-click the tray icon to
   open the control room or quit.
5. **Talk to it.** Say **"Wivexx"**, wait for the dot to perk up, and ask away.
   (Say **"stand down"** to dismiss.)

## What it can do

- **Natural conversation** with Claude, spoken and on-screen.
- **Long-term memory** — it remembers facts about you across sessions.
- **Calendar** — check and manage your Google Calendar (optional setup).
- **Photo / file delivery & import** — pull media off a drive and deliver it.
- **Goals** — track what you're working on, with a focus overlay.
- **Open & close apps by voice** — "open Chrome", "close Discord". Wivexx finds
  whatever's installed on your PC automatically (from your Start Menu).
- **Pick your microphone** — open the control room → **Settings → Microphone** and
  choose which mic Wivexx listens to (handy if you have more than one).
- **Optimize your PC** — "optimize my PC" frees up RAM and shows what's using your
  CPU/GPU, so you know what to close.
- **Global hotkeys** and a **screen UI** overlay.
- **Voice ID** so it knows it's you, plus **wake-word customization**.
- A **web control room** that mirrors wivexx.com, and a minimalist floating orb.

## Optional setup

- **Google Calendar / Drive:** see [`docs/DRIVE_SETUP.md`](docs/DRIVE_SETUP.md). You
  supply your own `credentials.json` from Google Cloud.
- **Phone relay:** see [`docs/RELAY_SETUP.md`](docs/RELAY_SETUP.md).
- **Raspberry Pi remote wake / wake-on-LAN:** the helper scripts live in
  [`extras/raspberry_pi/`](extras/raspberry_pi/) and run on the Pi, not the PC.

## Project layout

```
Wivexx.bat / Wivexx.vbs      launchers (Wivexx.vbs runs it silently)
start_wivexx.bat             first-run launcher (installs dependencies)
wivexx_api.py                entry point
wivexx_*.py                  feature modules
ui/                          the web control room (HTML/CSS/JS)
wivexx.ico / wivexx.png      app icon
docs/                        optional-setup guides
extras/raspberry_pi/         Raspberry Pi companion scripts
.env.example                 template for your API keys
```

## Privacy — before you share this folder

These files are **personal** and are already listed in `.gitignore`. Delete them
before zipping or publishing this folder for anyone else:

- `.env` (your API keys)
- `credentials.json`, `wivexx_*_token.json` (your Google OAuth)
- `wivexx_memory.db` (your memories), `usage.json`
- `wivexx_voiceprint.json` / `.npy`, `wivexx_calibration.json`
- `wivexx_hotkeys.json`, `wivexx_media_devices.json`, anything in `conversations/`

## Troubleshooting

- **"Python not found"** — reinstall Python with "Add to PATH" checked, then reboot.
- **A package "FAILED" to install** (e.g. `pygame`, `webrtcvad-wheels`, `moderngl`) —
  this means your **Python is too new** for that package's prebuilt installer.
  Optional extras are skipped automatically and Wivexx still runs. If a *required*
  package fails, install **Python 3.12** (64-bit), delete `.wivexx_preflight.json`,
  and run `start_wivexx.bat` again. (Running as Administrator does **not** help — the
  package just has no installer for your Python version.)
- **No response to your voice** — check Windows mic permissions and that the right
  input device is selected in the control room.

## Make a desktop shortcut

Double-click **`Create Desktop Shortcut.vbs`** once — it puts a **Wivexx** icon on
your Desktop that launches Wivexx silently. (Run it again if you move the folder.)
Or right-click `Wivexx.vbs` → *Send to → Desktop (create shortcut)*.

## License

No open-source license is set yet — **choose one before any public release.**
