Introduction

HamBros is a source-available agent observability platform for monitoring, managing, and orchestrating AI agent sessions. It provides a unified dashboard to watch agents work in real-time, manage commander personas, schedule recurring tasks, and collect telemetry data.

Core Concepts

HamBros is built around modules — each one handles a distinct aspect of agent operations:

Module	Purpose
Agents Monitor	Live session view with WebSocket streaming and interactive terminal
Commanders	GitHub-backed personas with memory, heartbeat, and quest boards
Command Room	Cron scheduler with task management and run history
Telemetry Hub	OTLP/HTTP ingestion with cost tracking and trace visualization
Factory	Session creation wizard with worktree-based workers
Services	API key management and service configuration

Architecture

┌─────────────────────────────────────────────┐
│                 HamBros App                  │
├──────────┬──────────────────────────────────┤
│  React   │         Express Server           │
│  SPA     │  ┌─────────┐  ┌──────────────┐  │
│          │  │ Modules  │  │  WebSocket   │  │
│  Vite    │  │ (routes) │  │  Streaming   │  │
│  Build   │  └─────────┘  └──────────────┘  │
├──────────┴──────────────────────────────────┤
│              Shared Packages                 │
│  @hambros/auth · @hambros/telemetry · cli   │
└─────────────────────────────────────────────┘

The frontend is a React SPA built with Vite and styled with the sumi-e design system — a Japanese ink-wash inspired visual language. The backend runs on Express with module-based routing and real-time WebSocket streaming.

Tech Stack

Frontend: React 19, Vite, TailwindCSS, React Query
Backend: Express, node-pty, WebSocket (ws)
Auth: Auth0 (optional) + API key authentication
Mobile: Capacitor for iOS builds
Monorepo: pnpm workspaces

Next Steps

Installation — set up your local environment
Configuration — environment variables and auth
First Agent Session — launch your first monitored agent