Welcome to Loom

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• ARCHITECTURE.md
• ROADMAP.md
• loom-py/README.md
• loom-py/src/loom/cli/README.md
• apps/market-analyst/README.md
• core/src/dashboard/README.md
• loom-py/src/loom/runtime/config.py
• observability/README.md
• loom-audio/README.md

Loom is an event-driven AI agent runtime designed to enable AI agents to run continuously, respond to real-world events, and collaborate across different processes. Unlike a library which is called by your code, Loom is a runtime that runs your agents as long-running services. This fundamental difference allows Loom to support long-lifecycle agents that can be triggered by system events like hotkeys, file changes, or timers, rather than just direct code calls.

The project's vision is to build a runtime for desktop and edge agents that feature proper context engineering and observable reasoning. It facilitates cross-process and cross-language agent collaboration through a central Event Bus, with a strong emphasis on secure tool execution by sandboxing tools within the Rust core.

Sources: README.md:7-10, ROADMAP.md:3-5, ARCHITECTURE.md:3-11

Core Architecture: The Brain/Hand Separation

Loom's architecture is founded on the "Brain/Hand Separation" principle. This design splits responsibilities between a Python-based "Brain" for fast iteration on AI logic and a Rust-based "Hand" for stable, secure, and performant execution of tasks.

Sources: ARCHITECTURE.md:13, ROADMAP.md:11

This diagram illustrates the separation of concerns between the Python agent and the Rust Core.

Responsibility Matrix

The following table details which part of the system is responsible for each core function.

Component	Rust Core	Python SDK	Agent Code
Event Bus	✅	-	-
Tool Execution	✅ (sandbox)	-	-
Agent Lifecycle	✅	-	-
Persistent Store	✅	-	-
MCP Proxy	✅	-	-
LLM Calls	❌	✅ (direct HTTP)	-
Cognitive Loop	❌	✅	-
Context Engineering	❌	✅	-
Business Logic	-	-	✅

Sources: ROADMAP.md:27-40

Key Components

Loom is composed of several key parts that work together to provide the full agent runtime experience.

Rust Core Runtime

The "Hands" of the system, the Rust Core is responsible for stable, secure, and performant infrastructure tasks.

• Event Bus: An async pub/sub system for agent communication with different Quality of Service (QoS) levels.
• Tool Registry: A unified, sandboxed environment for executing tools, including native Rust tools and external tools via the Model-Context-Protocol (MCP).
• Agent Lifecycle: Manages agent registration, heartbeats, and restarts.
• Persistent Store: A RocksDB-backed storage for long-term agent memory.
• System Integration: Provides capabilities for desktop agents, such as file monitoring, global hotkeys, and clipboard access.

Sources: ARCHITECTURE.md:55-88

Python SDK (loom-py)

The loom-py SDK is the primary way for developers to build the "Brain" of their agents. It provides high-level abstractions to interact with the Rust Core.

• Agent: The base class for connecting an agent to the Loom runtime, subscribing to topics, and emitting events.
• CognitiveAgent: A specialized agent that implements a perceive-think-act cognitive loop, integrating LLM-based reasoning and tool use.
• LLMProvider: A utility for making direct HTTP calls to LLM APIs, keeping prompt engineering and model selection logic within the Python environment for rapid iteration.
• ctx.tool(...): A context method for invoking tools securely executed by the Rust Core.

Sources: loom-py/README.md:9, ARCHITECTURE.md:90-117

Command-Line Interface (CLI)

Loom provides a powerful CLI for managing the runtime and interacting with agents.

Command	Description
loom up	Starts the full Loom runtime, including Core, Bridge, and Dashboard. It automatically downloads binaries if needed.
loom down	Gracefully stops all Loom-related processes, including the runtime and any running agents.
loom run	Runs a project, automatically discovering and starting agents defined within it.
loom chat	Starts an interactive terminal session to chat with a cognitive agent.
loom init	Creates a new Loom project from a template.

Sources: loom-py/src/loom/cli/README.md:11-23

Multi-Agent Collaboration

Agents in Loom collaborate asynchronously through the Event Bus, publishing and subscribing to topics rather than using direct function calls. This enables robust, cross-process communication.

This diagram shows how multiple agents can communicate via the central Event Bus.

Example: Market Analyst System

The Market Analyst application is a practical example of a multi-agent system where specialized agents collaborate to analyze market data in real-time.

Getting Started

You can get started with Loom by installing the Python SDK and starting the runtime.

1. Install the Python SDK:

   pip install loom-py
   

   Sources: README.md:68

2. Start the Loom Runtime:
   This command automatically downloads pre-built Rust binaries, caches them, and starts the runtime.

   loom up
   

   Sources: loom-py/README.md:28-31

3. Create and Run an Agent:
   Save the following code as my_agent.py and run it with python my_agent.py.

   from loom import Agent, tool
   
   @tool("web.search", description="Search the web for information")
   def web_search(query: str) -> dict:
       return {"query": query, "results": ["example.com"]}
   
   async def on_event(ctx, topic, event):
       # Echo payload back
       await ctx.emit(topic, type="echo", payload=event.payload)
   
   agent = Agent(
       agent_id="py-agent-1",
       topics=["topic.test"],
       tools=[web_search],
       address="127.0.0.1:50051",  # Connects to the runtime
   )
   
   if __name__ == "__main__":
       agent.run()
   

   Sources: loom-py/README.md:70-89

Observability

Loom includes a built-in observability stack to monitor agent behavior in real-time.

Dashboard

The Loom Dashboard provides a live view of the system, accessible at http://localhost:3030 when the runtime is started with loom up. Its features include:

• Live Event Stream: A streaming list of all events flowing through the bus.
• Agent Network Graph: An animated graph showing active agents and the message flows between them.
• Metrics: Displays for events/sec, active agents, and more.

Sources: core/src/dashboard/README.md:3-5, 17-23

Tracing and Metrics

Loom has full support for OpenTelemetry, allowing it to export detailed traces and metrics. This enables integration with tools like Jaeger, Prometheus, and Grafana for in-depth performance analysis and debugging.

This diagram shows the flow of telemetry data from Loom Core to various observability tools.

Configuration (loom.toml)

Projects are configured using a loom.toml file. This file allows you to define settings for the bridge, LLM providers, MCP tool servers, and agent-specific parameters. The configuration system supports environment variable expansion (e.g., ${MY_API_KEY}).

# loom.toml

[bridge]
address = "127.0.0.1:50051"

[dashboard]
enabled = true
port = 3030

[llm.deepseek]
type = "http"
api_key = "${DEEPSEEK_API_KEY}"
api_base = "https://api.deepseek.com/v1"
model = "deepseek-chat"

[mcp.brave]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
env = { BRAVE_API_KEY = "${BRAVE_API_KEY}" }

[agents.planner-agent]
llm_provider = "deepseek"
timeout_ms = 3000

Sources: loom-py/src/loom/runtime/config.py:10-21, 148-185, apps/market-analyst/README.md:92-120

Summary

Loom provides a robust, event-driven runtime for building, deploying, and managing long-running AI agents. Its unique "Brain/Hand" architecture separates fast-iterating AI logic in Python from a secure, high-performance Rust core. This design, combined with a powerful CLI, multi-agent collaboration via an Event Bus, and built-in observability, makes Loom a comprehensive platform for developing sophisticated AI systems that can interact with the real world.

Sources: README.md, ARCHITECTURE.md, ROADMAP.md