How nickvasilescu/bot-hq works
Bot HQ lets a user manage a team of Hermes agents: configure a bot and its apps, send work in chat or by voice, and follow progress and computer activity. The browser talks to the server over HTTP/SSE and VNC; the server coordinates agent turns, persistence, tools, schedules, screens, and integrations. The README documents the major product branches and external services. Some server modules are unsampled, so their internal call paths are omitted where the excerpts and index do not establish them.
Main entry points: routes.ts HTTP and event routes · App.tsx Browser interface · tools.ts Agent tools · engine.ts Hermes gateway manager
Components 27
Web app
- Browser interface
web/src/App.tsx - Client state
web/src/store.ts - Chat and transcript
web/src/components/ChatView.tsx - Tasks view
web/src/components/config/TasksView.tsx - Computer viewer
web/src/components/ComputerViewer.tsx - Voice interface
web/src/voice/call.ts
Server orchestration
- HTTP and event routes
server/src/routes.ts - Bot configuration routes
server/src/routes-config.ts - Room routes
server/src/routes-rooms.ts - Session authentication
server/src/lib/auth.ts - SQLite state
server/src/db.ts - Bot and task state
server/src/store.ts - SSE event hub
server/src/lib/hub.ts
Agent capabilities
- Hermes gateway manager
server/src/engine.ts - Agent turn loop
server/src/agent/loop.ts - Agent tools
server/src/agent/tools.ts - Bot messaging
server/src/agent/rooms.ts - Routines and triggers
server/src/routines.ts - Hermes memory
server/src/engine-memory.ts
Computer runtime
- Computer and screens
server/src/computer.ts - Desktop control
server/src/desk.ts - Screen presentation
server/box/hqlib.py
External services
- Hermes gateways
- Orgo
- Composio apps
- xAI voice and search
Other components
- User
Connections 36
- User → Browser interface: uses
README.md - Browser interface → Client state: loads state
web/src/App.tsx - Browser interface → Chat and transcript: renders
web/src/App.tsx - Browser interface → Tasks view: renders
web/src/App.tsx - Browser interface → Computer viewer: renders
web/src/App.tsx - Client state → HTTP and event routes: HTTP requests
- Browser interface → HTTP and event routes: HTTP and SSE
README.md - Browser interface → Computer and screens: VNC connection
README.md - Voice interface → HTTP and event routes: voice requests
- HTTP and event routes → Session authentication: authenticates
server/src/routes.ts - Bot configuration routes → Session authentication: authenticates
server/src/routes-config.ts - Room routes → Session authentication: authenticates
server/src/routes-rooms.ts - HTTP and event routes → Agent turn loop: starts turns
README.md - HTTP and event routes → Hermes gateway manager: routes turns
README.md - HTTP and event routes → Routines and triggers: manages routines
README.md - HTTP and event routes → Bot and task state: reads and writes
server/src/routes.ts - Bot configuration routes → Hermes gateway manager: configures bots
server/src/routes-config.ts - Room routes → Bot messaging: manages rooms
server/src/routes-rooms.ts - Bot and task state → SQLite state: persists state
server/src/store.ts - Bot and task state → SSE event hub: emits events
server/src/store.ts - Bot messaging → Bot and task state: uses state
server/src/agent/rooms.ts - Bot messaging → SSE event hub: emits events
server/src/agent/rooms.ts - Agent turn loop → Agent tools: invokes tools
- Agent tools → Composio apps: connects apps
README.md - Agent tools → xAI voice and search: searches X
README.md - Agent tools → Routines and triggers: offers tasks
README.md - Agent tools → Bot messaging: messages bots
README.md - Hermes gateway manager → Hermes gateways: HTTP responses
README.md - Hermes gateways → HTTP and event routes: MCP tools
README.md - Hermes gateway manager → Computer and screens: gets screen
server/src/engine.ts - Computer and screens → Orgo: manages screens
server/src/computer.ts - Computer and screens → Desktop control: controls desktop
server/src/computer.ts - Computer and screens → Screen presentation: sets display
- Hermes gateway manager → Hermes memory: provides bot home
server/src/engine-memory.ts - Routines and triggers → Bot and task state: uses persistence
server/src/routines.ts - Voice interface → xAI voice and search: realtime voice
README.md