How helloeveryboby/butler works
Butler is a local-first personal assistant, with Python coordinating conversational AI, skills, automation, memory, and optional native services. A typical user flow enters through the assistant or terminal UI, passes through intent/agent handling, and reaches a skill or workflow execution result. The repository also documents voice, document, storage, hardware, and hybrid-language capabilities. Some connections below come from README descriptions or file references in the source index; unsampled implementation details are not inferred as confirmed calls.
Main entry points: butler_app.py Assistant runtime · executor.py Action executor · engine.py Workflow engine · main.py Terminal interface
Components 24
User interaction
- Terminal interface
butler/tui/main.py - Command catalog
butler/tui/command_catalog.py - Command panel
butler/CommandPanel.py - Voice service
butler/core/voice_service.py
Assistant orchestration
- Assistant runtime
butler/butler_app.py - Runtime environment
butler/core/environment.py - Intent understanding
butler/core/nlu_service.py - Agent planning
butler/agent/agent.py - Action executor
butler/agent/executor.py - Workflow engine
butler/workflow/engine.py - Event bus
butler/core/event_bus.py
Skills and capabilities
- Skill manager
butler/core/skill_manager.py - Package loader
butler/package_runtime/loader.py - Document tools
package/document/file_converter.py - Translation engine
package/document/translate_system/engine.py
Memory and state
- Long-term memory
butler/core/memory/memory_engine.py - Plugin data storage
butler/data_storage.py - Dream engine
butler/core/dream_engine.py - Self-healing
butler/core/self_healing.py
System integrations
- Hybrid link
butler/core/hybrid_link.py - Hardware manager
package/device/hardware_manager.py - Cloud storage hub
package/storage_hub/storage_hub.py
Other components
- User
- External services
Connections 27
- User → Assistant runtime: starts
README.md - User → Terminal interface: uses
README.md - Assistant runtime → Runtime environment: initializes
butler/butler_app.py - Assistant runtime → Event bus: uses
butler/butler_app.py - Assistant runtime → Command panel: uses
butler/butler_app.py - Assistant runtime → Voice service: uses
butler/butler_app.py - Assistant runtime → Intent understanding: uses
butler/butler_app.py - Assistant runtime → Skill manager: uses
butler/butler_app.py - Assistant runtime → Long-term memory: uses
butler/butler_app.py - Terminal interface → Command catalog: uses
butler/tui/main.py - User → Voice service: speaks to
README.md - Intent understanding → Agent planning: routes intent
- Agent planning → Action executor: plans actions
butler/agent/agent.py - Action executor → Package loader: loads packages
butler/agent/executor.py - Workflow engine → Action executor: executes steps
butler/workflow/engine.py - Workflow engine → Package loader: loads packages
butler/workflow/engine.py - Skill manager → User: offers skills
README.md - Assistant runtime → Dream engine: integrates memory
README.md - Assistant runtime → Self-healing: supports recovery
README.md - Assistant runtime → Hybrid link: uses hybrid link
README.md - Assistant runtime → Hardware manager: supports hardware
README.md - Assistant runtime → Document tools: offers document tools
README.md - Document tools → Translation engine: includes translation
README.md - Assistant runtime → Cloud storage hub: supports cloud storage
README.md - Assistant runtime → Plugin data storage: stores plugin data
butler/butler_app.py - Long-term memory → External services: optional Redis
README.md - Cloud storage hub → External services: connects storage
package/storage_hub/storage_hub.py