How musabduman/ghost-operator-v2 works
Ghost is a local-first personal AI assistant. Its documented workflow accepts voice or chat, routes work through a LangGraph supervisor/worker and critic, dispatches tools, and returns a response; memory captures activity and distills durable facts. The graph also preserves project memory, voice, UI, and integrations. Some subsystems are documented but their implementation was not sampled, so those links cite the README; the separate prime-agent tree and flight simulator are not part of Ghost’s described product.
Main entry points: command_handler.py Command handler · main.py Desktop UI · llm.py Supervisor and workers · server.py Core server
Components 19
User interaction
- Desktop UI
legacy/ui_v1/main.py - Web UI
frontend/src/App.jsx - Voice handler
handler/voice_handler.py - Core server
server.py - Session store
sessions/session_manager.py
Agent and tools
- Supervisor and workers
ai/llm.py - Tool registry
core/tool_registry.py - Command handler
handler/command_handler.py
Memory
- Episodic log
hafıza/episodic_db.py - Librarian agent
ai/librarian_agent.py - RAG memory
hafıza/rag_hafıza.py - Project memory
hafıza/project_memory.py - Project symbol map
hafıza/symbol_graph.py
Machine integrations
- File operations
core/fs.py - WhatsApp
tools/whatsapp_tool.py - Screen vision
vison/vison.py - Spotify
kontrol/spotify.py - Browser tool
tools/browser_tool.py
Other components
- User
Connections 21
- User → Desktop UI: sends input
- Desktop UI → Command handler: submits commands
legacy/ui_v1/main.py - Desktop UI → Voice handler: uses voice
legacy/ui_v1/main.py - Desktop UI → Session store: loads sessions
legacy/ui_v1/main.py - User → Web UI: sends chat
frontend/src/App.jsx - Web UI → Core server: WebSocket chat
frontend/src/App.jsx - Core server → Command handler: dispatches
server.py - Core server → Session store: uses sessions
server.py - Command handler → Supervisor and workers: runs agent
handler/command_handler.py - Supervisor and workers → Tool registry: uses schemas
ai/llm.py - Supervisor and workers → Command handler: dispatches tools
handler/command_handler.py - Command handler → File operations: calls file tools
handler/command_handler.py - Command handler → WhatsApp: calls WhatsApp
handler/command_handler.py - Command handler → Screen vision: calls vision
handler/command_handler.py - Command handler → Browser tool: calls browser
handler/command_handler.py - Command handler → Spotify: uses integration
handler/command_handler.py - Supervisor and workers → Episodic log: logs activity
- Librarian agent → Episodic log: reads unanalyzed logs
- Librarian agent → RAG memory: stores extracted facts
- Command handler → Project memory: injects project rules
- Command handler → Project symbol map: uses project symbols