How gui-bertoso/maya works
Maya is a local-first desktop voice assistant. The main workflow captures speech, recognizes a command, processes it asynchronously, and presents a response through the overlay and speech output. Command handling also covers routines, memory and vocabulary, plus desktop, web, music, and workspace automation. The graph includes major documented capabilities and substantial indexed modules. Some connections are documented or inferred rather than visible in sampled call sites; those are dashed and unverified. Paths identify source implementations, not every data file they may use.
Main entry points: process.py Command processing · app.py Desktop lifecycle · renderer.py Overlay and UI · memory.py Conversation memory
Components 26
Input and experience
- Voice recognition
input/voice.py - Clap detection
input/clap_detector.py - Desktop lifecycle
app.py - Overlay and UI
output/renderer.py - Speech output
output/speaker.py - Window showcase
helpers/window_showcase.py
Command orchestration
- Async input pipeline
core/input_pipeline.py - Command processing
core/process.py
Personal state
- Conversation memory
core/memory.py - Knowledge base
core/knowledge_base.py - Vocabulary manager
core/vocabulary_manager.py - Routine scheduling
core/routine_manager.py - Local JSON state
data
Automation
- App launcher
helpers/app_launcher.py - Web assistant
helpers/web_assistant.py - Spotify assistant
helpers/spotify_assistant.py - Developer workspace
helpers/dev_assistant.py - Workspace tools
helpers/dev_workspace.py - Thoughtful workspace
helpers/thoughtful_workspace.py
Runtime support
- Safe persistence
helpers/backup_manager.py - Localization
helpers/i18n.py - Runtime configuration
helpers/config.py
Other components
- Person
- Desktop environment
- Web services
- Spotify client
Connections 35
- Person → Voice recognition: speaks to
README.md - Voice recognition → Desktop lifecycle: delivers transcripts
app.py - Clap detection → Desktop lifecycle: signals wake
app.py - Desktop lifecycle → Async input pipeline: submits work
app.py - Async input pipeline → Command processing: runs callback
- Desktop lifecycle → Command processing: processes commands
app.py - Command processing → Desktop lifecycle: dispatches UI events
core/process.py - Desktop lifecycle → Overlay and UI: updates interface
app.py - Desktop lifecycle → Speech output: speaks responses
app.py - Command processing → Conversation memory: records conversation
core/process.py - Command processing → Knowledge base: uses knowledge
core/process.py - Command processing → Vocabulary manager: uses vocabulary
core/process.py - Command processing → Routine scheduling: handles routines
core/process.py - Conversation memory → Safe persistence: loads and saves
core/memory.py - Vocabulary manager → Safe persistence: loads and saves
core/vocabulary_manager.py - Routine scheduling → Local JSON state: persists progress
- Conversation memory → Local JSON state: persists memory
- Vocabulary manager → Local JSON state: persists vocabulary
- Command processing → App launcher: dispatches automation
- Command processing → Web assistant: dispatches web tasks
- Command processing → Spotify assistant: dispatches music tasks
- Command processing → Developer workspace: dispatches dev tasks
- Command processing → Workspace tools: delegates workspace
- Command processing → Thoughtful workspace: dispatches workspace
- App launcher → Desktop environment: launches apps
- Web assistant → Web services: uses online services
- Spotify assistant → Spotify client: opens and searches
- Overlay and UI → Window showcase: uses window tools
output/renderer.py - Overlay and UI → Workspace tools: uses workspace tools
output/renderer.py - Overlay and UI → Thoughtful workspace: uses workspace tools
output/renderer.py - Overlay and UI → Localization: localizes interface
output/renderer.py - Command processing → Runtime configuration: reads settings
core/process.py - Conversation memory → Runtime configuration: resolves storage path
core/memory.py - Routine scheduling → Runtime configuration: resolves storage path
core/routine_manager.py - Voice recognition → Runtime configuration: reads audio settings
input/voice.py