Skip to content
Looms
Documentation
On this page

When to use Looms

Looms is a TypeScript execution runtime that you deploy in your own infrastructure. Use it when several kinds of work need to share durable state: an agent delegates to a workflow, a custom state machine waits for a webhook, and a human decides what happens next.

One run, many kinds of work#

A thread is a unit of execution with a kind and a state machine. Agents and DAG workflows are built-in kinds. Your own module can define a new kind using the same extension primitives. Threads nest within a run and share its ordered history, recovery, and projections.

For example, a procurement agent starts a review workflow, which spawns a custom auction thread. The auction accepts bids until a deadline, records a winner, and returns a result to the workflow. The debugger can show the whole operation without joining logs from unrelated runtimes.

Good fits#

  • Work that pauses for minutes or days on approvals, webhooks, or child results.
  • Applications that combine model-driven decisions with deterministic business rules.
  • Domain execution types that need more than a fixed agent loop or DAG.
  • Products whose UI, audit history, and runtime state should come from the same events.

Costs you take on#

You choose the host, enforce authorization, operate storage, and design compatible upgrades. Reducers must remain deterministic. External actions need idempotency or reconciliation. A single run has one writer. Put independent work in separate runs.

When a simpler approach is enough#

A single model request, a stateless tool call, or a short request-response API may not need Looms. If your existing durable workflow engine already handles your execution model, adopting another one adds migration and operational work. Start with a specific need for custom thread composition or a shared execution history.

How it fits existing tools#

  • Vercel AI SDK: keep its model providers. The Looms adapter calls the model while Looms schedules turns and tools. You do not run a second automatic tool loop alongside it.
  • Durable Objects: supply the actor isolation, SQLite, and alarm host. Looms supplies thread composition, event history, effects, and projections.
  • Temporal, Restate, DBOS, and other durable engines: Looms lets custom thread kinds share one run log. Compare the features and guarantees your application needs before switching.
  • Your existing agent loop: adapt one turn through runTurn or a model adapter. Record the outcomes of external actions so execution can recover after an interruption.

Release status and support#

Looms is an early 0.0.x library. Expect API evolution, pin the package version, and test recovery before production use. Cloudflare Durable Objects is the recommended production host; Bun with SQLite is the local path. Browser subpaths provide clients and projections. Custom hosts require you to preserve one writer per run.

Try a complete run, then read integration and reliability. Source and issues: ByteSliceHQ/looms.