Reyn

Architecture

How Reyn works.

A bird's-eye view of the components that make up Reyn, and how they coordinate to execute a single request.

01 At a glance

The whole system,
on one page.

Reyn is built from a small set of components. Agents hold long-lived conversations. Skills describe directed phase graphs. Phases loop the LLM through one task at a time. The OS runs everything under a strict validation contract. Workspace and Events make every step inspectable and replayable.

flowchart TB U(["User / External System"]) subgraph I01["01 · Interface"] direction LR CLI["CLI"] ~~~ TUI["TUI (Textual)"] ~~~ WEB["Web UI (FastAPI + WebSocket)"] end subgraph I02["02 · Agent Registry"] direction LR AM["manages named agents"] ~~~ TG["Topology gate — network · team · pipeline"] end subgraph I03["03 · Agent = ChatSession"] direction LR RL["RouterLoop (LLM-driven dispatch)"] ~~~ PL["Planner (optional · plan mode)"] ~~~ MEM["memory scope · skill allowlist"] end subgraph I04["04 · OS — the constant"] direction LR CB["Context Build"] ~~~ LC["LLM Call"] ~~~ VA["Output Validation"] ~~~ EE["Event Emit"] end subgraph I05["05 · Skill"] direction LR PG["Phase Graph + Transitions"] ~~~ FO["final_output_schema"] ~~~ PP["Postprocessor"] end subgraph I06["06 · Phase"] direction LR PRE["Preprocessor"] ~~~ LO["LLM + Control IR ops"] ~~~ LP["↺ loops until transition/finish"] end subgraph I07["07 · Persistence"] direction LR WS["Workspace (artifacts · files)"] ~~~ EV["Events (append-only log)"] end U --> I01 --> I02 --> I03 --> I04 --> I05 --> I06 --> I07
02 The pieces

Five components.
Sharp boundaries.

Each component has one job. Agents don't know about Phases. Phases don't know about Skills. The OS is the only layer that touches all of them — and it never embeds skill-specific logic.

Agent

A long-lived ChatSession. RouterLoop dispatches messages to Skills, an optional Planner decomposes complex goals, memory scope and skill allowlist define what the agent can see and do.

Skill

A directed graph of Phases. Owns the entry phase, the allowed transitions, and the final-output schema. Cycles are first-class — revision loops are a feature, not a workaround.

Phase

The execution unit. Declares an input contract and instructions, runs a preprocessor, calls the LLM, dispatches Control IR ops. Loops until it decides to transition or finish.

OS

The runtime engine. Builds context, validates LLM output against schemas, executes ops under permission gates, emits an event for every state change. Constant; never embeds skill specifics.

State

Workspace is the single source of truth for inter-phase data. Events is an append-only log of every transition, op call, and decision. Together they make crash recovery and replay possible.

03 A request, end to end

From message
to reply.

sequenceDiagram participant U as User participant A as Agent (ChatSession) participant PL as Planner (optional) participant SK as Skill graph participant PH as Phase loop participant WS as Workspace + Events U->>A: message alt Complex multi-step request A->>PL: plan_task(goal) PL-->>A: Plan { steps: [S1, S2, ...] } Note over A: each step → skill invocation else Simple request Note over A: RouterLoop picks Skill directly end A->>SK: invoke skill SK->>PH: enter entry phase loop Until transition or finish PH->>PH: preprocessor (deterministic) PH->>PH: LLM call (closed candidate set) PH->>PH: validate output against schema PH->>WS: execute Control IR ops · emit events PH-->>SK: result + control decision alt decision = transition Note over SK: validate against next.input_schema SK->>PH: enter next phase else decision = finish Note over SK: validate against final_output_schema opt postprocessor declared (skill-level) SK->>WS: postprocessor steps · emit events end SK-->>A: final output end end A-->>U: reply

A user message arrives at an Agent. The RouterLoop picks a Skill. The OS enters the entry Phase, runs its preprocessor, calls the LLM with a closed candidate set, and validates the response. Control IR ops are dispatched under permission gates and write to the Workspace. An event records each step. The Phase either transitions to a peer or finishes; the OS validates the final output against the Skill's schema and the reply travels back to the user.

04 Beyond a single agent

Reyn talks out.
Reyn is talked to.

Agents delegate to other Agents asynchronously through a topology gate — network, team, or pipeline — with hop depth capped at three. From outside, Reyn exposes itself as an MCP server: Claude Code, Cursor, and any MCP-aware client can call list_agents() and send_to_agent(). Inside Phases, Control IR ops can call external MCP servers as well — third-party tools come under the same permission gate and event log as everything else.

sequenceDiagram participant U as User (depth=0) participant A as Agent A (depth=1) participant B as Agent B (depth=2) participant C as Agent C (depth=3=limit) U->>A: message Note over A: RouterLoop → delegate_to_agent A->>B: send(to=B, depth=1, chain_id=xyz) Note over B: RouterLoop → delegate_to_agent B->>C: send(to=C, depth=2, chain_id=xyz) Note over C: depth=3 = max_hop_depth C-->>B: result (chain_id=xyz) B-->>A: result (chain_id=xyz) A-->>U: final reply Note over A,C: chain timeout = 60s
flowchart LR subgraph SRV["MCP Server — implemented (reyn mcp serve)"] direction TB EXT["External LLM Client\nClaude Code · Cursor · OpenAI SDK"] STDIO["stdio / JSON-RPC 2.0"] TOOLS["list_agents() · send_to_agent()"] AR["AgentRegistry → ChatSession"] EXT --> STDIO --> TOOLS --> AR end subgraph CLI2["MCP Client — implemented (stdio · HTTP)"] direction TB PHASE["Reyn Phase (control_ir)"] MCIROP["MCPIROp kind: mcp"] MCLIENT["MCPClient\nstdio / HTTP transport"] EXTMCP["External MCP Server"] PHASE --> MCIROP --> MCLIENT --> EXTMCP end

Go deeper in the docs.

The concepts section covers each component in detail — with design rationale, edge cases, and links to the implementation.

Read the concepts → ← Back to home