Loop Architecture

Four principles

1. 1
   Loop Thinking.

   Make the agentic loop between systems your unit of design. Think in loops, not just boxes.

2. 2
   Continuous and autonomous.

   A loop is not a one-off. It keeps turning on its trigger, using systems and writing back on its own, again and again.

3. 3
   Self-Learning.

   Each turn learns from the last. The loop measures its effect and improves how it decides over time.

4. 4
   Human on the loop.

   A human supervises the whole, not every run. They spot-check with samples and focus on the results and their quality, not on reviewing each turn.

Examples

A Loop Architecture is one YAML file. Edit it on the left and the diagram on the right updates live: the systems, the agentic loops, and the edges between them. Pick an example, or click any system or loop for details.

Open the full-screen editor →

The format

One plain YAML file with three top-level keys, id, systems, and loops. Each loop uses (observe) systems and writes back to (act) systems. A trigger is a 5-field cron, an ISO timestamp, a GitHub event, or manual.

id: your-org
systems:
  - id: dash0
    url: https://dash0.com            # favicon becomes the icon
    connector: dash0
  - id: code-repo
    repository: https://github.com/your-org/app
  - id: docs
    url: https://docs.your-org.com
loops:
  - id: triage-incidents
    name: Triage Incidents
    trigger: "*/5 * * * *"            # cron | ISO time | github event | manual
    model: claude-opus-4-8          # the model this loop runs on
    observe: [dash0]                # systems it uses
    act: [jira, slack]            # systems it writes back to
    instructions: Detect incidents; open a Jira ticket and post to Slack
  - id: sync-docs
    name: Sync Docs
    trigger:                        # one trigger, or several
      - "0 6 * * *"
      - pull_request.merged
    observe: [code-repo]
    act: [docs]
    instructions: >                     # what the loop does each turn
      Diff the docs against changes merged in the last 24h and open a PR.
    tools: [Read, Grep, Bash(gh pr *)]

Specification → JSON schema → Full example →

Tooling

Two tools work directly with a Loop Architecture YAML: the looparch visualizer to see it, and the looparch CLI to validate, visualize and sync it.

looparch visualizer

A small, embeddable component (built on React Flow) that reads a Loop Architecture YAML and maps it to the interactive diagram above itself: the systems, the agentic loops, and the edges between them. Drop it into any page, or open it from the CLI with looparch view.

// the bundle includes React + React Flow; just load it and its CSS
import { mountEditor, createController } from './visualizer/dist/visualizer.js';

// editable: YAML editor + live diagram
mountEditor(document.getElementById('editor'), { examples: [ ... ] });

// or read-only: the visualizer parses the YAML itself
createController(document.getElementById('flow')).show('your-org.looparch.yaml');

Open the editor →

looparch CLI

A Python CLI (built with uv) to validate, visualize and sync loops.

$ uv tool install looparch

$ looparch init your-org              # scaffold an architecture
$ looparch validate your-org.looparch.yaml    # schema + lint
$ looparch view your-org.looparch.yaml        # open the interactive diagram
$ looparch sync your-org.looparch.yaml     # → Claude Code routines
$ looparch sync ./my-project --from-claude  # ← reverse: routines back to YAML

sync writes, for each loop, a slash command (.claude/commands/loop-<id>.md) and a routine descriptor (.claude/routines/<id>.json) with the loop's schedule/event, model, and repos.

CLI reference →

Loop Storming

Loop Storming is a collaborative workshop for discovering loops, in the spirit of Event Storming. The team maps the systems, connects them into loops (what each loop uses and writes back to), names them, writes their instructions, and sets triggers. The messy wall is your initial map; you then refine it into a formal Loop Architecture YAML.

Read the Loop Storming guide →

FAQ

What is Loop Architecture?

Loop Architecture is an architecture style that makes the agentic loop between systems the first-class unit of design. A loop is triggered on a schedule or event, uses one or more systems, follows its instructions, and writes back to those systems. A Loop Architecture is all of your loops, mapped together in one diagram.

What is an agentic loop?

An agentic loop is a continuous cycle where an agent reads from (uses) one or more systems, follows its instructions toward a goal, and writes back to systems, again and again on its trigger. It runs continuously and is self-learning.

What is Loop Storming?

Loop Storming is a collaborative workshop for discovering the agentic loops between your systems, in the spirit of Event Storming. You map the systems (focusing on data, source code and storage), connect them into loops, name them, and set triggers.

How do I sync a loop to Claude Code?

Encode your loops in one Loop Architecture YAML file and run looparch sync. Each loop becomes a Claude Code routine: a slash command plus a schedule or event trigger.

What is looparch?

looparch is a Python CLI (built with uv) that validates, visualizes and syncs a Loop Architecture to Claude Code routines, and reads them back with --from-claude.

How is Loop Architecture different from event-driven or microservice architecture?

Traditional architecture designs the systems and the requests between them. Loop Architecture designs the agentic loops that run continuously between those systems, each using some systems and writing back to others.

Who created Loop Architecture?

Loop Architecture was coined by Arif Wider and Simon Harrer at SummerSOC on 1 July 2026, on the island of Crete. Read the origin story →