Crate Reference

Workspace Overview

The workspace crates that make up the product:

loop/
├── crates/
│   ├── loop-ai/            # Unified LLM API
│   ├── loop-agent/         # Agent harness
│   ├── loop-app-core/      # Shared bootstrap for CLI + desktop
│   ├── loop-cli/           # Terminal UI
│   ├── loop-desktop/       # GPUI desktop (beta, Rust nightly)
│   ├── loop-mcp/           # MCP client and server (default)
│   ├── loop-orchestration/ # Multi-agent workflows (feature: orchestration)
│   └── loop-telemetry/     # OTLP / Langfuse traces (feature: telemetry)
└── Cargo.toml

loop-test-support is a dev helper and is not part of the binary.

loop-ai

Unified LLM API layer — provider abstraction, streaming, auth, and cost tracking.

Modules

Module	Purpose
`api/`	Wire adapters (OpenAI Chat Completions compatible)
`auth/`	Credential resolution (env vars → auth.json)
`models/`	`Models` collection and model specifications
`models_store/`	Dynamic model catalog cache
`providers/`	Soket, custom, and faux (testing) providers
`stream/`	`AssistantMessageEvent` streaming protocol
`types/`	`Context`, `Message`, `Tool` core types
`utils/`	Cost calculation, context estimation, tool validation

Key Types

// Core message types
pub struct Message { ... }
pub struct Context { ... }
pub struct Tool { ... }

// Streaming events
pub enum AssistantMessageEvent {
    Text(String),
    Thinking(String),
    ToolCall { id, name, arguments },
    Done,
    Error(String),
}

Provider Abstraction

All providers implement the same interface, making model switching seamless. The faux provider enables deterministic testing without API calls.

loop-agent

Agent runtime — the core harness that orchestrates LLM calls, tools, sessions, and sandbox.

Architecture

┌─────────────────────────────────────────┐
│  AgentHarness (entry point)             │
│    prompt() │ start_workflow()           │
│    start_workflow_from_goal()            │
│    (+ optional progress_tx)              │
├─────────────────────────────────────────┤
│  Agent (stateful transcript)            │
│  agent_loop (turn execution)            │
├─────────────────────────────────────────┤
│  harness/                               │
│    session/  tools/  sandbox/           │
│    compaction/  hooks/  skills/         │
│    orchestration/  mcp/                 │
└─────────────────────────────────────────┘

Modules

Module	Purpose
`agent.rs`	`Agent` struct — stateful transcript, steering queue
`agent_loop.rs`	Turn execution loop
`harness/`	`AgentHarness` orchestrator
`harness/session/`	Session store backends (memory, JSONL, SQLite)
`harness/tools/`	Built-in tool implementations
`harness/sandbox/`	Sandbox factory, Podman integration
`harness/compaction/`	Context compaction logic
`harness/hooks/`	Lifecycle hook system
`harness/skills/`	Skill loader and manager
`harness/mcp/`	MCP client integration (feature: `mcp`, on by default)
`harness/orchestration/`	Orchestration bridge (feature: `orchestration`)

Adapter Layer

Module	Feature Flag	Purpose
`harness/orchestration/`	`orchestration`	`AgentWorker`, `ShellWorker`, `SubWorkflowWorker`, memory tools, `WorkflowProgressEvent`
`harness/mcp/`	`mcp`	`LoopToolProvider` (implements `ToolProvider`), `bridge.rs` (MCP↔AgentTool conversion)

Session Backends

Backend	Implementation	Features
Memory	`MemorySessionStore`	Ephemeral, fast, for testing
JSONL	`JsonlSessionStore`	Append-only files, one per session
SQLite	`SqliteSessionStore`	Durable, FTS, migrations, concurrent access

All backends implement the SessionStore trait and are accessed through SessionRepository.

loop-app-core

Shared application core — bootstrap, config, theme, and tool-approval wiring used by both CLI and desktop. Surfaces differ only in presentation; harness and config paths are shared.

loop-cli

Terminal UI — ratatui-based TUI, slash commands, configuration loading, and runtime bootstrap.

Modules

Module	Purpose
`app.rs`	Application state and event loop
`tui/`	ratatui rendering (markdown, tool cards, workflow cards, status bar)
`commands/`	Slash command registry and handlers
`config/`	Settings loading, auth, models, trust
`runtime.rs`	Tokio runtime bootstrap

TUI Stack

ratatui 0.30 — Terminal UI framework
crossterm 0.28 — Terminal backend
syntect — Syntax highlighting
pulldown-cmark — Markdown parsing

Workflow Progress UI

With --features orchestration, /workflow streams live WorkflowTask cards (pending → success/error) with description and collapsible output (Ctrl+O).

loop-desktop

GPUI desktop app — sessions sidebar, streaming chat, diff review, PTY dock.

Area	Behavior
Layout	Sessions sidebar \| chat + composer \| diff review; PTY dock (`Ctrl+“)
Chat	Markdown, collapsible thinking, click-to-expand tool cards, file-change chips
Review	Diff panel with accept/reject, external editor, tool-approval modal
Theme	Light/dark toggle persisted via `settings.theme`

Shares harness wiring through loop-app-core and a DesktopController that coalesces agent events into UI snapshots (~60fps). Live multi-agent workflow task cards remain CLI-only for now. Requires Rust nightly:

export RUSTUP_TOOLCHAIN=nightly
cargo run -p loop-desktop -- .

loop-mcp

MCP protocol — client manager and server implementation (linked into the default binary).

Components

Component	Purpose
`McpClientManager`	Manages connections to external MCP servers
`bridge.rs`	Bridges MCP tools into `AgentTool` format
`McpServer`	HTTP server exposing Loop tools via MCP
`LoopToolProvider`	Implements `ToolProvider` for Loop’s built-in tools

Dependencies

rmcp — Rust MCP SDK
axum 0.8 — HTTP server
tower 0.5 — HTTP middleware

CLI: loop --serve-mcp listens for streamable HTTP on 127.0.0.1:3100. --mcp-host changes the interface; a non-loopback address requires --mcp-token.

loop-telemetry

Traces — OpenTelemetry export to Langfuse or any OTLP/HTTP collector (feature: telemetry). Spans cover the agent run, a model generation, and tool calls. In the CLI this is /tracing plus the --trace-* flags on --print. Settings for the destination are global; secrets stay in the credential store. See Tracing.

loop-orchestration

Multi-agent workflow engine — planning, scheduling, memory, and event sourcing (plugin crate).

Modules

Module	Purpose
`planner/`	`LlmPlanner`, `ManualPlanner` — goal → TaskGraph
`workflow/`	Event-sourced state machine, `subscribe()`, `WorkflowResult`
`scheduler/`	Dispatch loop with concurrency control
`memory/`	SharedMemory, TaskMemory, MemoryBus

Traits Defined

AgentRunner, ShellRunner — abstract interfaces for task execution
Decoupling: serde_json::Value at the crate boundary (avoids coupling to loop-agent types)
Feature: sqlite for optional SqliteEventLog

Worker Trait

#[async_trait]
pub trait Worker: Send + Sync {
    async fn execute(&self, context: WorkerContext) -> WorkerResult;
}

Implement this trait to add custom worker types to the orchestration engine.

Dependency Graph

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

loop-mcp is part of the default loop binary. The orchestration and telemetry plugin crates are absent from it. The agent implements their traits only when the feature is enabled.

​Workspace Overview

​loop-ai

​Modules

​Key Types

​Provider Abstraction

​loop-agent

​Architecture

​Modules

​Adapter Layer

​Session Backends

​loop-app-core

​loop-cli

​Modules

​TUI Stack

​Workflow Progress UI

​loop-desktop

​loop-mcp

​Components

​Dependencies

​loop-telemetry

​loop-orchestration

​Modules

​Traits Defined

​Worker Trait

​Dependency Graph

Workspace Overview

loop-ai

Modules

Key Types

Provider Abstraction

loop-agent

Architecture

Modules

Adapter Layer

Session Backends

loop-app-core

loop-cli

Modules

TUI Stack

Workflow Progress UI

loop-desktop

loop-mcp

Components

Dependencies

loop-telemetry

loop-orchestration

Modules

Traits Defined

Worker Trait

Dependency Graph