How koshikraj/birdie works
Birdie is a local agent-to-agent messaging service: agents submit messages through MCP or HTTP, the bus tracks threads and delivery, and messages reach pull sessions or external webhook/ACP agents. The CLI supports installation, onboarding, setup, health checks and session management; the web UI provides agent, message and activity views. Backend excerpts were not supplied, so backend links below rely on explicit README statements; frontend links use the sampled source.
Main entry points: bus.go Message bus · App.tsx UI application · client.ts API client · hooks.ts Query hooks
Components 28
CLI and setup
- Setup and onboarding
cmd/birdie/setup.go - Guided onboarding
cmd/birdie/onboard.go - Service management
cmd/birdie/service.go - Session commands
cmd/birdie/thread.go
Agent interfaces
Messaging core
- Message bus
internal/bus/bus.go - Address routing
internal/bus/address.go - Message events
internal/bus/events.go - SQLite state
internal/store/sqlite.go
Delivery adapters
- ACP adapter
internal/adapter/acp.go - Webhook adapter
internal/adapter/webhook.go - Hermes integration
integrations/hermes/__init__.py
Web interface
- Web UI API
internal/webui/api.go - Web UI auth
internal/webui/auth.go - Web UI server
internal/webui/webui.go - UI application
web/src/App.tsx - Agent and message pages
web/src/pages/Agents.tsx - Activity dashboard
web/src/pages/Dashboard.tsx - API client
web/src/api/client.ts - Event stream client
web/src/api/events.ts - Query hooks
web/src/api/hooks.ts - Message visualization
web/src/scene/Scene.tsx - UI routing
web/src/lib/router.ts
Other components
- Operator
- Local agents
- Remote agents
Connections 31
- Operator → Guided onboarding: runs setup
- Guided onboarding → Setup and onboarding: configures agents
- Setup and onboarding → MCP tools: connects agents
- Service management → Message bus: starts service
- Local agents → MCP tools: sends via MCP
- MCP tools → Message bus: submits messages
- Remote agents → HTTP API: sends HTTP
- HTTP API → Message bus: submits messages
- Message bus → Address routing: resolves recipient
- Message bus → SQLite state: stores state
- Message bus → ACP adapter: delivers headlessly
- Message bus → Webhook adapter: posts messages
- Webhook adapter → Remote agents: sends webhook
- ACP adapter → Remote agents: reaches agent
- Local agents → Hermes integration: connects through
- Message bus → Message events: publishes changes
- Operator → UI application: opens UI
- UI application → UI routing: selects view
web/src/App.tsx - UI application → API client: signs in
web/src/App.tsx - UI application → Event stream client: starts stream
web/src/App.tsx - UI application → Query hooks: loads overview
web/src/App.tsx - Agent and message pages → Query hooks: queries data
web/src/pages/Agents.tsx - Activity dashboard → Query hooks: queries data
web/src/pages/Dashboard.tsx - Query hooks → API client: calls endpoints
web/src/api/hooks.ts - Event stream client → API client: checks session
web/src/api/events.ts - Event stream client → UI application: invalidates queries
web/src/App.tsx - Activity dashboard → Message visualization: renders activity
web/src/pages/Dashboard.tsx - API client → Web UI API: requests UI API
- Web UI server → Web UI API: serves UI API
- Web UI server → Web UI auth: uses authentication
- Session commands → Message bus: manages sessions