Skip to article
LoopingLouieDocs
Browse docs
Start looping
On this page
  1. Platform boundaries
  2. Configuration resolution
  3. Harnesses
  4. Worker provisioning and admission
  5. Execution lifecycle
  6. Results, history, and human steps
  7. Related concepts

Overview

Looping Louie Architecture

Looping Louie coordinates iterative LLM-assisted software development. It separates durable workflow decisions from local repository execution: the API persists Pipeline and Activity state, while runtime workers execute approved work in explicitly configured Git checkouts.

The platform is independent from any programming language, framework, or LLM provider.

Platform boundaries

The API is the durable control plane. It manages Users and Projects, reusable Activities and Pipelines, provider connections, prompt generation, model and Harness selection, checkpoint transitions, and commit authorization.

The runtime is the local execution plane. It maps Projects to configured checkouts, inspects repositories, applies approved filesystem operations, invokes local Harnesses, evaluates local Git policy, and performs an authorized commit. It never accepts a checkout path from an API response.

The API never directly mutates a target repository. The runtime does not make model, reviewer, or scheduling decisions. The dashboard and CLI are API clients for users who manage resources, start work, and inspect results.

Configuration resolution

Users may set default models and Harnesses. Pipelines and Activities may override either setting, and loop agents may override the model. At Pipeline-run creation, the API resolves and freezes effective values:

  • Model: agent, Activity, Pipeline, then User.
  • Harness: Activity, Pipeline, then User.

An unset Harness becomes the louie v1 compatibility default. A Pipeline edit cannot change the frozen model or Harness used by an existing run.

Personas provide reusable instructions, not provider routing. For each CLI Harness Activity, the API freezes the requested model, selected Persona, and ordered Skills in the Activity snapshot. The runtime receives this immutable input and does not fetch mutable instruction resources while executing a turn.

For the API-directed louie Harness, an effective model must resolve to a compatible, enabled, configured Linked Service. codex_cli and copilot_cli do not use API Linked Services or API provider credentials; their authentication remains local to the runtime worker.

Harnesses

A Harness is the local execution mechanism for a runtime-executable Activity. It is different from an Activity agent: agents act as generators, reviewers, or aggregators using a Persona and model; a Harness carries out the Activity in a configured checkout and reports a normalized result.

The API-directed louie Harness collects context, applies API-approved file operations, gathers review input, and commits only after API authorization. The codex_cli and copilot_cli Harnesses support direct_loop, refinement_loop, and roundtable_loop Activities. The API persists one run_harness checkpoint for each writer, proposal, review, or aggregation turn, so Harness adapters share loop semantics and commit policy.

Harness definitions have a stable kind, version, and kind-specific config object. The current louie, codex_cli, and copilot_cli v1 configurations are empty. Executable paths, sandbox policy, timeouts, credentials, and other machine configuration remain runtime-owned.

Worker provisioning and admission

The API provisions a durable worker identity for each configured Project. On first start, the runtime detects local Harnesses, registers the worker, and stores the assigned ID in its Project configuration. It refreshes a heartbeat before polling and replaces its advertised Harness capabilities on each heartbeat.

A worker advertises local Harness health, not available models. It always advertises louie; it advertises codex_cli only when the configured command is installed and authenticated, and copilot_cli when its configured command is available. Detection refreshes periodically so local sign-in changes are reported without changing the worker identity.

A Pipeline-run claim requires an active heartbeat and an exact match between the next Activity’s frozen Harness and the worker’s advertised capability. A run remains queued while no compatible worker is healthy and can become claimable after a later heartbeat. Readiness exposes aggregate counts and the required Harness, not Worker identities or local configuration.

Execution lifecycle

flowchart LR
R[Runtime worker] -->|Claim next Pipeline run| A[Looping Louie API]
A -->|Run, Activity child, and lease token| R
R -->|Read and execute checkpoint action| G[Configured Git checkout]
R -->|Renew lease and submit checkpoint| A
R -->|Continue Pipeline with lease token| A
A -->|Next Activity child or terminal state| R

The runtime polls at most one run per Project per cycle. It can process the next scheduled children in the same checkout until a Pipeline is terminal. A project-level operational failure is logged without preventing other Projects from being polled; unexpected runtime defects stop the worker.

Each successful claim includes a short-lived lease token. The runtime renews it before every checkpoint and Pipeline continuation, and submits it with each checkpoint result. A background keepalive renews it during a blocking CLI turn. The API validates lease ownership before generation and atomically before every durable transition, preventing stale or replaced workers from advancing a run.

The standard checkpoint actions are:

  • collect_snapshot: the runtime sends bounded repository context.
  • apply_operations: it validates and atomically applies API-provided changes.
  • run_harness: it executes the selected local coding-agent turn.
  • submit_review_input: it sends the final diff and bounded changed content.
  • commit_if_allowed: it applies captured local Git policy and commits only when both local policy and the API permit it.

Results, history, and human steps

Every run_harness result uses a versioned observation envelope with the frozen Harness identity. It reports turn identity, timing, requested and actual model, usage, process outcome, Git diff, changed files, response, diagnostics, and an optional session reference. Harness adapters may add fields such as materialized Skill versions or Codex reasoning effort.

The API rejects a result whose Harness differs from the frozen selection and a successful result whose requested model differs from the snapshot. It preserves partial observations from failed processes. Pipeline runs retain an append-only event ledger for creation, claims, step transitions, and Harness outcomes.

For commit-enabled CLI runs, the Harness proposes a non-empty commit message. The API records it and returns it only at commit_if_allowed; the runtime may still deny the commit under its local Git policy. A forbid commit mode never emits a commit checkpoint.

Human approval and quiz Activities do not use a Harness. A ready human step creates an Activity run with the human executor and transitions the Pipeline to waiting. A user submits the decision through the Activity-run API. A rejection resets frozen predecessor steps for corrective execution before a new human step is created.

  • Activities explains Activity categories and loop roles.
  • Harnesses provides the focused Harness guide.
  • Executions describes the checkpoint lifecycle.
  • Providers explains providers, models, and Linked Services.