loom-run — official Loom stack showcase

Official reference product for the Loom stack — not a generic agent framework, but the runnable demo that wires loom-runner + flow-xray into a local-first durable chat agent with multi-agent supervisor.

Keywords: durable agents · checkpoint resume · multi-agent orchestration · MCP tools · local-first · SQLite · inspectable runs · LangGraph alternative (runtime slice)

User message  →  coordinator (LLM + tools)  →  loom-runner checkpoint/resume  →  flow-xray --trace
                      ↑ supervise → subagent runs (v0.2)

What this repo is

If you want libraries to compose → start with loom-runner.
If you want see it all working in 30 seconds → clone this repo.
If you want incident/deploy runbooks (not dev chat) → loom-ops.

More: Showcase guide · Architecture

Loom stack position

The stack is a pyramid, not five equal frameworks. Tail-call optimization is the primitive, runner is the durable runtime, xray is the microscope, and the apps prove the stack in real workflows.

loom-run is not loom-runner. loom-runner is the reusable runtime kernel; this repo is the runnable chat/dev showcase that proves the kernel, traces, MCP tools, and supervisor pattern work together.

Install

From PyPI:

pip install "loom-run[api,openai]"
loom-run chat "explain checkpoint policy" --run-id demo --db runs.sqlite --mock-llm

From source:

git clone https://github.com/kroq86/loom-run.git
cd loom-run
python3.13 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api,openai]"

Ecosystem map: loom-stack ECOSYSTEM.md

Demo commands (copy-paste)

Single agent (mock LLM, no API key):

loom-run chat "explain checkpoint policy" --run-id demo --db runs.sqlite --mock-llm
loom-run resume --run-id demo --db runs.sqlite --max-steps 20
loom-run explain --run-id demo --db runs.sqlite
loom-run chat "explain checkpoint policy" --run-id demo2 --db runs.sqlite --mock-llm --trace trace.html

Multi-agent supervisor (v0.2):

loom-run supervise "explain checkpoint policy" --run-id team-demo --db runs.sqlite --mock-llm
loom-run explain --run-id team-demo:sub:researcher --db runs.sqlite

HTTP SSE (optional):

loom-run serve --db runs.sqlite --mock-llm
curl -N -X POST http://127.0.0.1:8765/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"explain checkpoint policy","run_id":"demo","max_steps":20}'

Tools

MCP config: mcp.servers.example.json · env: docs/ENV.md

Extended ecosystem map

Tests

python -m pytest -q              # 21 tests incl. subprocess E2E
python -m pytest -q tests/test_e2e.py

Docs

• Showcase & discovery — SEO, links, positioning
• Architecture
• Environment variables

License

MIT · kroq86