Create a team of AI agents, give them a goal in plain language, and watch them plan, delegate, build, and review — collaboratively, in real time.
Gamma Runtime is a multi-agent orchestration platform where each agent is a persistent Claude Code CLI session running on your machine. You assemble a team — a Team Lead plus specialists like Backend Developer, Frontend Developer, and QA — then hand the lead a goal. The lead decomposes the work into stages and tasks, delegates to the right specialists, reviews their output, and drives the project to completion. Every thought, tool call, message, and task transition streams to the browser as it happens.
There are no external LLM gateways and no API keys. All model calls go
through the local claude CLI under your existing subscription. State lives in a
local Postgres instance; everything runs with a single docker compose up.
This project is the engineering artifact of an MSc thesis on multi-agent runtime systems. It is the local-first approach — a focused rewrite that trades infrastructure for simplicity. An earlier, heavier architecture (a microkernel runtime with a Redis Streams memory bus and agent-generated micro-apps) is preserved on the
legacy-v1branch.
| Most agent frameworks | Gamma Runtime |
|---|---|
| Call an LLM API with your keys | Drives the local claude CLI under your subscription — zero API keys |
| A single agent loops over tools | A team of agents with a lead that delegates and reviews |
| Opaque "black box" reasoning | Every action streams live via SSE — fully traceable |
| Cloud-coupled | Local-first — one docker compose up, your data stays on disk |
| Heavyweight infra (Redis, queues, brokers) | Single instance, in-memory event bus — deliberately minimal |
flowchart TB
subgraph Browser["🖥️ Browser · React"]
direction LR
AM[Agent Map]
CP[Chat Panel]
TB[Task Board · Kanban]
end
subgraph Backend["⚙️ NestJS Backend · Fastify"]
direction LR
ORC["<b>Orchestrator</b><br/><i>the core</i>"]
AG[Agents]
TM[Teams]
API["Internal API<br/>agent-facing"]
EB["Event Bus<br/>in-memory"]
TR["Trace · log"]
CLI["Claude CLI Adapter<br/>child_process.spawn"]
end
PG[("Postgres<br/>state")]
CC["claude CLI × N<br/>one process per active agent<br/>isolated workspaces"]
Browser <==>|"REST + Server-Sent Events"| Backend
ORC --> AG & TM & API & CLI
Backend --> PG
CLI ==> CC
style ORC fill:#4F46E5,stroke:#312E81,color:#fff
style CLI fill:#4F46E5,stroke:#312E81,color:#fff
style CC fill:#22D3EE,stroke:#0E7490,color:#06283D
style PG fill:#9333EA,stroke:#581C87,color:#fff
The orchestration loop:
- You send a message to the team →
POST /api/teams/:id/message. - The Orchestrator spawns the Team Lead as a
claudeCLI process. - The lead reads an auto-generated
CLAUDE.mdin its workspace (team context, task list, API docs) and decomposes the goal into tasks. - The lead delegates →
POST /api/internal/assign-task. - The Orchestrator catches the
task.assignedevent and spawns a worker agent for it. - The worker completes its task →
POST /api/internal/update-task. - When all tasks finish, the lead is auto-woken to review and continue.
- Every step streams to the browser over SSE — live.
Agents coordinate by calling a small internal REST API (assign tasks, update status, message peers, broadcast, read shared context) — the same way a human team would use a tracker and a chat.
- 🧑🤝🧑 Team-based orchestration — a Team Lead decomposes goals, delegates to specialists, and reviews their work.
- 🔌 Subscription-powered, no API keys — every agent is a local
claudeCLI session; nothing leaves your machine except the calls Claude Code makes. - 📡 Real-time everything — thoughts, tool use, messages, and task transitions stream to the UI via Server-Sent Events.
- 🗂️ Visible task board — a live Kanban (
backlog → planning → in_progress → review → done) reflecting what agents are actually doing. - 🧩 160+ community roles — drop-in agent personalities across engineering, product, design, research, QA, marketing, and more.
- 🧵 Isolated workspaces — each agent gets its own sandboxed directory; shared files and plans live in a common team space.
- 🧾 Immutable trace log — a complete, replayable audit trail of every agent action.
- 🛑 Emergency stop — kill all running agent processes instantly (SIGTERM → SIGKILL).
- 🐳 One-command setup —
docker compose upfor Postgres,pnpm devfor the apps.
| Layer | Technology |
|---|---|
| Backend | NestJS 10 · Fastify · TypeScript · raw pg (no ORM) · EventEmitter2 |
| Frontend | React 18 · Vite · Zustand · Tailwind CSS · TypeScript |
| Agents | Claude Code CLI (--output-format stream-json, spawned per agent) |
| Storage | PostgreSQL 16 (via Docker) |
| Transport | REST + Server-Sent Events (no WebSockets, no Redis) |
| Tooling | pnpm workspaces · ESLint 9 (flat config) · Prettier · GitHub Actions |
- Node.js ≥ 22 and pnpm 9 (
corepack enablewill provide pnpm) - Docker (for Postgres)
- Claude Code CLI installed and
authenticated (
claudeavailable on yourPATH)
# 1. Clone and install
git clone https://github.com/serhiizghama/gamma-runtime.git
cd gamma-runtime
pnpm install
# 2. Configure environment
cp .env.example .env
# 3. Start Postgres
pnpm db:up
# 4. Run backend + frontend
pnpm devThen open http://localhost:5173. The backend listens on http://localhost:3001.
The schema is applied automatically on first boot — no manual migration step.
Create a team, open the chat, and give the Team Lead a goal — for example:
"Build an MVP banking website with authentication and a dashboard."
The lead will draft a plan, break it into tasks, delegate to the Backend and Frontend developers, review their output, and hand off to QA — all visible in the UI.
pnpm dev # Run backend + frontend together
pnpm dev:core # Backend only (NestJS watch, port 3001)
pnpm dev:web # Frontend only (Vite, port 5173)
pnpm build # Build both apps
pnpm typecheck # Type-check both apps (no emit)
pnpm lint # ESLint across the workspace
pnpm format # Format with Prettier
pnpm format:check # Verify formatting (used in CI)
pnpm db:up # Start Postgres
pnpm db:down # Stop Postgres
pnpm db:reset # Wipe and restart Postgres (drops all data)gamma-runtime/
├── apps/
│ ├── core/ # NestJS backend (~5k LOC)
│ │ └── src/
│ │ ├── orchestrator/ # Spawns & coordinates agents — the heart
│ │ ├── claude/ # Claude CLI adapter + session pool
│ │ ├── internal/ # Agent-facing REST API
│ │ ├── sse/ # Server-Sent Events streaming
│ │ ├── events/ # In-memory event bus
│ │ ├── repositories/ # Data access (raw pg)
│ │ ├── agents/ # Agent CRUD, workspaces, roles
│ │ └── trace/ # Immutable activity log
│ └── web/ # React frontend (~4.5k LOC)
│ └── src/
│ ├── pages/ # Dashboard, TeamDetail, TraceViewer
│ ├── hooks/ # SSE + data hooks
│ ├── store/ # Zustand state
│ └── api/ # Fetch client
├── community-roles/ # 160+ agent role definitions
├── scripts/ # DB init & migrations
└── docker-compose.yml # Postgres
- IDs are ULIDs with entity prefixes (
team_,agent_,task_). - Timestamps are millisecond epoch integers stored as
BIGINT. - SQL is always parameterized — never string-concatenated.
- No Redis — a single instance with an in-memory event bus keeps the architecture intentionally simple.
Released under the MIT License © 2026 Serhii Zghama.