Architecture Overview

Overview

Loop is a Cargo workspace. The default path is a terminal TUI (loop-cli) or, separately, a GPUI desktop beta (loop-desktop). Both sit on loop-app-core. MCP is in the default build. Orchestration and telemetry are crates you opt into with Cargo features.

High-Level Architecture

loop-cli / loop-desktop
    └── loop-app-core
          └── loop-agent
                ├── loop-ai                         (always)
                ├── loop-mcp            feature mcp (default)
                ├── loop-orchestration  feature orchestration
                └── loop-telemetry      feature telemetry

Dependency flow: loop-cli / loop-desktop → loop-app-core → loop-agent → loop-ai. loop-mcp is linked by default. loop-orchestration and loop-telemetry are optional and are not linked unless the matching feature is on.

Request Flow

A typical agent turn follows this flow:

User Input
    │
    ▼
AgentHarness.prompt()
    │
    ├── Load context files (AGENTS.md)
    ├── Inject system prompt + skills
    │
    ▼
Agent Loop
    │
    ├── Build messages (transcript + new input)
    ├── Call LLM via loop-ai
    │      │
    │      ├── Provider selection
    │      ├── Auth resolution
    │      └── Streaming response
    │
    ├── Parse response
    │      │
    │      ├── Text → Render to TUI / desktop
    │      ├── Thinking → Show/hide per config
    │      └── Tool calls → Dispatch
    │
    ├── Tool Dispatch
    │      │
    │      ├── Permission check
    │      ├── Sandbox routing
    │      ├── Execution (parallel or sequential)
    │      └── Result collection
    │
    ├── Append results to transcript
    └── Loop back to LLM (if tool calls present)
         │
         └── Until no more tool calls → Turn complete

Workflows use start_workflow / start_workflow_from_goal instead of prompt(), with an optional progress channel for live WorkflowProgressEvents (task started / completed / failed).

Design Principles

Separation of Concerns

Each crate owns a distinct layer:

loop-ai knows nothing about tools, sessions, or UI
loop-agent knows nothing about TUI or desktop rendering
loop-app-core shares bootstrap/config between surfaces
loop-cli / loop-desktop are the only crates with UI code
loop-orchestration is fully optional (feature-gated)

Trait-Based Abstraction

Key extension points use traits:

Trait	Purpose
`SessionStore`	Pluggable session backends (memory, JSONL, SQLite)
`SandboxFactory`	Custom sandbox implementations
`ToolProvider`	Bridge external tools (MCP) into the agent
`Worker`	Custom orchestration worker types
`AgentRunner` / `ShellRunner`	Abstract task execution for orchestration

Event Sourcing (Orchestration)

The orchestration layer uses event sourcing for all state transitions:

Every action is recorded as an event
State can be rebuilt by replaying events
subscribe() broadcasts live events; harness progress channel feeds UI cards
Enables debugging, forking, and recovery

Streaming Throughout

From LLM response to UI rendering, everything streams:

AssistantMessageEvent protocol carries streaming chunks
TUI / desktop render markdown incrementally
Tool and workflow task cards update in real-time

Session Data Model

Sessions form a tree structure:

root
├── message-1 (user)
│   └── message-2 (assistant)
│       ├── message-3 (user)         ← branch A
│       │   └── message-4 (assistant)
│       └── message-5 (user)         ← branch B (fork)
│           └── message-6 (assistant)

Each message has a parent pointer, enabling:

Branching at any point
Multiple continuations from the same message
Tree navigation with /tree
Session forking with /fork

Feature Flags

# loop-agent
[features]
default = ["sqlite", "proxy"]
sqlite = ["dep:rusqlite"]
proxy = ["dep:reqwest", ...]
mcp = ["dep:loop-mcp", "dep:rmcp"]
orchestration = ["dep:loop-orchestration"]
telemetry = ["dep:loop-telemetry"]

# loop-cli  (default = ["mcp"])
mcp = ["loop-agent/mcp", "loop-app-core/mcp", "dep:loop-mcp", ...]
orchestration = ["loop-agent/orchestration", "dep:loop-orchestration"]
telemetry = ["loop-agent/telemetry", "loop-app-core/telemetry", "dep:loop-telemetry"]

sqlite — SQLite sessions (on by default in loop-agent)
proxy — HTTP client for model calls (on by default in loop-agent)
mcp — MCP client and --serve-mcp (on by default in loop-cli)
orchestration — /workflow (off)
telemetry — /tracing and --trace-* (off)

Build Targets

Loop builds as a single optimized binary:

Target	Platform
`x86_64-apple-darwin`	macOS Intel
`aarch64-apple-darwin`	macOS Apple Silicon
`x86_64-unknown-linux-gnu`	Linux x86_64
`aarch64-unknown-linux-gnu`	Linux ARM64
`x86_64-pc-windows-msvc`	Windows x64

Release builds use LTO, single codegen unit, and symbol stripping for minimum binary size.

​Overview

​High-Level Architecture

​Request Flow

​Design Principles

​Separation of Concerns

​Trait-Based Abstraction

​Event Sourcing (Orchestration)

​Streaming Throughout

​Session Data Model

​Feature Flags

​Build Targets