Belsebu

Asistente de escritorio Windows con interfaz por voz para Claude Code.

Pulsás Win+B, hablás, Belsebu captura audio + screenshot, transcribe localmente, envía contexto a Claude vía claude -p (subscripción OAuth, 0 tokens extra), ejecuta las acciones que Claude responde (shell, teclado, archivos, control de ventanas), y habla la respuesta por TTS local (Piper).

Por qué existe

Rafael — el predecesor — usaba un router LLM local (qwen3:4b) que decidía intents en JSON estructurado. Limitaba a comandos pre-definidos. Belsebu delega todo el razonamiento a Claude y Belsebu solo es el ejecutor: captura, ejecuta tools, habla. Esto da:

• Razonamiento más rico (Claude Opus/Sonnet vs qwen3:4b).
• Capacidad de modificarse a sí mismo: Claude puede editar shortcuts.yaml, system_prompt.md, agregar nuevos handlers.
• Interfaz natural para "hablarle a Claude Code": en vez de tipear en la terminal, hablás.

Para intents triviales (subir volumen, abrir Spotify), Belsebu hace bypass de Claude usando shortcuts.yaml — latencia <100ms sin llamar al LLM.

Arquitectura rápida

┌──────────── Windows nativo (Python 3.12) ────────────┐
│                                                       │
│  AHK Win+B ──► ffmpeg + mss ──► POST /trigger ──►    │
│                                                       │
│  Coordinator (FastAPI :8766)                          │
│   ├── STT (faster-whisper local, GPU)                │
│   ├── Shortcuts matcher (regex → skip Claude)        │
│   ├── Claude runner (subprocess claude -p, JSON out) │
│   ├── Action executor (shell, type, write, focus)    │
│   └── TTS (Piper local)                              │
│                                                       │
│  HUD overlay (tkinter, invisible a capturas)         │
│   └── reproduce TTS con winsound.PlaySound           │
└───────────────────────────────────────────────────────┘

Stack

Capa	Tecnología	Local/Red
Trigger	AutoHotkey v2	Local
Audio	ffmpeg DirectShow PCM s16le 16k mono	Local
Screenshot	mss (DXGI)	Local
STT	faster-whisper small (GPU RTX 3060 → CPU fallback)	Local
Razonamiento	claude -p por OAuth subscription	Red (sin tokens extra)
TTS	Piper ONNX es_MX-ald-medium (CPU, 63MB)	Local
HUD	tkinter + WDA_EXCLUDEFROMCAPTURE + winsound	Local
Coordinator	FastAPI + uvicorn	Local

Estado

🚧 En construcción. Ver phases en el task list o docs/STATUS.md.

Setup

Requisitos: Windows 10/11, Python 3.12, Claude Code CLI autenticado por OAuth, AutoHotkey v2 y ffmpeg en el PATH. GPU NVIDIA recomendada (hay fallback a CPU).

git clone https://github.com/NicolasCuaran/belsebu.git
cd belsebu
.\setup\install.ps1     # crea .venv, instala deps y registra las tareas

• Despertar / dormir el asistente: .\setup\wake.ps1 / .\setup\sleep.ps1 (PowerShell elevado).
• La memoria de runtime vive en .belsebu/ (ignorada por git). Parte de .belsebu/LongTermMEMORY.example.md.

Contribuir

¡Las contribuciones son bienvenidas! Lee CONTRIBUTING.md y el Código de Conducta antes de empezar.

Licencia

Distribuido bajo la licencia MIT. Ver LICENSE.