Relay

Every Employee. Amplified.

Relay is an AI Workforce Intelligence Platform. The long-term product direction is to give every employee an AI partner that connects organizational knowledge, business workflows, tools, and agent execution.

This repository contains the current local-first developer MVP. It has a Python/FastAPI backend control plane, TypeScript daemon and TUI clients, a Next.js web UI, local event-sourced state under .relay/, and BoxLite-backed agent execution.

Current MVP

• Durable tasks, sessions, events, snapshots, and artifacts under .relay/.
• Task backlog and recurring routines in the web UI, with backend scheduler promotion and dispatch to ready daemon nodes.
• Human approval and handoff flows through the TUI.
• Daemon-based execution for Claude, Pi, Codex, and Kimi agent CLIs.
• Readable rendering for Claude stream JSON and Codex JSONL output.
• Token usage tracking across sessions and agents.
• Local HTTP APIs for tasks, sessions, daemon nodes, sandboxes, chat integrations, the control panel, and the exported web UI.
• Web UI with chat, backlog, routines, MCP, skills, channels, and an admin console (dashboard KPI tiles, fleet health, token usage charts, activity feed), node management, and user/department CRUD.
• Provider-neutral chat gateway (relay-chat) with Discord, Telegram, and Lark adapters.

Relay is control-plane-first: the backend owns task identity, workflow state, approval gates, audit trails, daemon coordination, and policy boundaries. Agent CLIs remain execution engines and run through daemons, not inside the backend.

Quick Start

npm install
npm test
make run

Common commands:

make backend        # Python backend on port 8790
make daemon         # TypeScript daemon connected to the backend
make run            # local TUI flow
make web            # Next.js web UI in dev mode
make serve          # backend/server mode on port 8787
make backend-migrate  # run Alembic database migrations
make stop           # stop backend, daemon, TUI, and BoxLite processes

For full setup, environment variables, BoxLite devbox export, local API routes, data layout, and test organization, see Local Development.

Documentation

• Local Development: setup, commands, environment, local services, data layout, source map, and tests.
• Product Design: product strategy, users, scenarios, positioning, roadmap, and business model.
• Architecture Design: target architecture, planes, runtime layers, sandbox strategy, MCP gateway, memory, and governance.
• Technical Implementation Design: deployable components, data model, APIs, runtime flows, security, observability, implementation phases, and current local implementation map.
• Chat Integrations: Discord, Telegram, and Lark adapter architecture, identity mapping, commands, security, and rollout.
• Architecture Decision Records: accepted technical decisions for governance, sandboxing, and control-plane boundaries.
• Visual Design: marketing/UI design language and visual system direction.
• Brand Assets: logo files, usage notes, and color tokens.

Architecture Snapshot

Relay is split into a control plane and an execution plane.

• backend/: Python/FastAPI backend split into core/ (models, env, ids), persistence/ (event-sourced session/task/daemon stores), security/ (auth), services/ (controller, daemon registry, task scheduler, chat integrations), and api/ HTTP routes. Top-level modules such as controller.py and daemon.py are compatibility re-exports. Alembic migrations live under backend/migrations/.
• packages/relay-core/: shared TypeScript protocol, command builders, prompts, renderers, token-usage normalization, and compatibility client exports.
• packages/relay-chat/: provider-neutral chat gateway; Discord, Telegram, and Lark adapters.
• packages/relay-daemon/: TypeScript daemon runtime, BoxLite integration, and agent process execution.
• packages/relay-tui/: Ink-based terminal UI.
• web/: Next.js web UI served at /web — chat, backlog, routines, MCP, skills, channels, and the admin console/dashboard.

The current local MVP keeps persistence file-backed under .relay/, but the event model is intended to map cleanly to durable database-backed storage.

Test Layout

• backend/tests/: Python backend unit and API tests (including task scheduler and routine promotion).
• packages/*/tests/: TypeScript package tests next to the owning package.
• web/tests/: web UI tests next to the Next.js app.

Run the active suite with:

npm test

Roadmap

The broader implementation roadmap remains in docs/implementation-plan.md. Recent MVP additions include task backlogs, recurring routines with backend scheduler dispatch, and web UI design-system refresh. Next major work areas are contract test coverage, storage parity, daemon/backend integration tests, and enterprise control-plane hardening.