Local Agent Loop Website

Local Agent Loop Website is a local-first Architect → Worker → Reviewer workflow built for iterative website development with small local models, real browser evidence, bounded memory and single-GPU specialist handoffs.

The technical package name stays local-agent-loop: Local Agent Loop Website is the website-specialized reference implementation of that package.

flowchart LR
    A["1. Architect<br/>chooses the next task"] -->|Phase Ledger| W["2. Worker<br/>implements the task"]
    W -->|Phase Ledger| R["3. Reviewer<br/>checks the result"]

    R -->|PASS| A
    R -->|FAIL · same task| W

    O[("Order Ledger<br/>durable memory")] -->|context| A
    O -.->|read-only context| R
    R -->|compact result| O

    W -.->|optional| I["Image Specialist"]

    classDef role fill:#ffffff,stroke:#4d9be6,stroke-width:2px,color:#0b2a66;
    classDef memory fill:#0b2a66,stroke:#75bdff,stroke-width:2px,color:#ffffff;
    classDef optional fill:#f7fbff,stroke:#8abcf0,stroke-width:1.5px,color:#174d96;

    class A,W,R role;
    class O memory;
    class I optional;

Loading

What it is

local-agent-loop turns a small local model into a structured website-building workflow. Instead of one growing chat trying to plan, implement, review, remember, and recover at the same time, the system separates those jobs and lets a deterministic control plane move only the state each role actually needs.

The reference setup was tested end-to-end on a Windows laptop with an RTX 3070 Laptop GPU (8 GB VRAM) using Qwen 3.5 9B for Architect, Worker, and Reviewer, driving a real local website with real browser evidence.

Built for iterative website development

The system exists so small local models can develop websites reliably, round after round. One model alone should never have to plan, implement, review, self-certify, and remember the whole history at once. Instead:

• Architect chooses exactly one next task.
• Worker implements exactly that frozen task (runtime/config key: developer).
• Reviewer checks the result against real rendered evidence.
• Control plane owns routing, lifecycle, and integrity — never product decisions.

How the loop works

1. /agent-loop-start <workspace> <max> --team arms the session (no role starts yet).
2. The next normal user prompt becomes the authoritative session goal.
3. The Architect emits exactly one task; the control plane freezes it (task_id, revision, objective, scope, acceptance). One frozen task is one bounded work package, not necessarily one tiny edit: it SHOULD normally bundle 2–4 tightly related improvements (same section, component, or user journey) expressed through separate acceptance criteria.
4. The Worker implements the frozen task and hands off a bounded result.
5. The Reviewer judges frozen acceptance criteria against rendered desktop/mobile evidence: PASS, FAIL, or BLOCKED.
6. FAIL returns the same frozen task to the Worker for repair; PASS archives a compact durable result into the Order Ledger and the next Architect plans the next task.

Review is evidence against a frozen contract, not a second planning step. The Reviewer cannot redefine the task, widen scope, or invent a new objective. Every frozen acceptance criterion carries a control-plane ID (<task-id>:AC-01, …); verdicts must reference exactly those IDs. The Reviewer reports failed frozen acceptance criteria and factual evidence. It does not prescribe the repair. Broader product_feedback is advisory only: it never decides the current verdict, and it is promoted only after the current frozen task is accepted — it never changes an active repair scope.

Website-first, but adaptable

Generic core (reusable for other applications):

• Architect / Worker / Reviewer roles and frozen tasks
• Acceptance criteria and PASS/FAIL semantics
• Order Ledger and Phase Ledgers
• Context isolation and restart recovery
• Fail-closed HOLDs
• GPU lease and specialist handoffs

Website-specific (this reference implementation):

• HTTP page rendering via headless Edge
• Desktop/mobile full-page evidence
• Responsive review against rendered pixels
• Browser console and visual checks
• HTML/CSS/JS workflows

Other applications can adapt the loop by exchanging, in particular, the evidence producer, the worker toolset, and the acceptance gates. Examples (not implemented out of the box): desktop apps via UI screenshots/automation, documents via PDF/Office rendering plus structural checks, data pipelines via schemas/tests/deterministic outputs, code/refactoring via tests/diffs/static checks, CAD/3D via render previews plus geometry checks.

Why this helps small local models

Common failure	Structural response
Goal drift	one frozen task at a time
Context overload	isolated fresh roles + bounded ledgers
Self-certification	independent Reviewer + rendered evidence
Long-run amnesia	bounded Order Ledger
Scope creep	immutable acceptance
VRAM contention	single-GPU lease
Invisible role execution	live role stream + heartbeat

Quick start

Requires Pi 0.85.1 or newer plus a local language/vision model runtime. No model weights or runtime binaries are included.

pi install git:github.com/neyisyavuz-afk/local-agent-loop

/reload

/agent-loop-setup

/agent-loop-team-models list
/agent-loop-team-thinking list
/agent-loop-image-models list

Then arm a website run:

/agent-loop-start C:\work\website 8 --team

The next normal user prompt becomes the authoritative goal and starts the Architect. Progress with /agent-loop-status, stop with /agent-loop-stop.

Update the package with pi update git:github.com/neyisyavuz-afk/local-agent-loop, remove it with pi remove git:github.com/neyisyavuz-afk/local-agent-loop.

Use either the Pi Git package or the manual extension installation as the active source, not both. A manual copy at ~/.pi/agent/extensions/agent-loop.ts next to the installed package registers every /agent-loop-* command twice, and duplicated commands can no longer be dispatched — they fall through to the model as plain text. The companion directory ~/.pi/agent/extensions/agent-loop/ may stay as a fallback, but there must be no second active agent-loop.ts. Manual development install: git clone … + pwsh ./scripts/install.ps1 + pwsh ./scripts/setup.ps1.

Roles and memory

Role	Main input	Main output
Architect	user goal + Order Ledger + current Reviewer delta/evidence when relevant	one frozen task / Architect Phase Ledger
Worker (developer)	current task handoff only	implementation + Worker Phase Ledger
Reviewer	frozen task + Worker Phase Ledger + browser/technical evidence + read-only Order context	PASS / FAIL / BLOCKED + Reviewer Phase Ledger
Control Plane	validated structured state	routing, persistence, expiry, recovery

The Project Ledger is the only cross-session semantic memory. The Order Ledger is the only session-scoped semantic memory. Architect and Reviewer may consult them; the Worker does not receive them. Phase Ledgers (Architect, Worker, Reviewer) are temporary one-shot handoffs with the lifecycle CREATED → HANDED_OFF → CONSUMED → EXPIRED. No growing agent chats.

Browser evidence

Website code alone is never sufficient evidence. Architect and Reviewer see real rendered pixels:

• Desktop evidence at 1440px width, mobile evidence at 390px width (responsive breakpoints preserved).
• Representative top-of-page shots at typical viewport sizes (desktop 1440×1000, mobile 390×844).
• Longer pages add lückenlose full-page coverage segments at the same width but a taller coverage height (1280px).

The Reviewer judges whether the rendered state meets the acceptance criteria — never whether "the code looks okay".

Long-page coverage, validated on a real ~9977px mobile page: previously 12 × 844 exceeded the bound of 8 and held fail-closed; now 1 representative 390×844 plus 8 × 390×1280 coverage segments cover the page with no gaps (coverageComplete: true). Extremely long pages still hold fail-closed instead of sampling with gaps.

Live role progress

While Architect, Worker, or Reviewer run, Pi shows live in the starting window, without any debug console:

• role, round, attempt, and elapsed time
• the frozen task visual flag (visual=yes / visual=no) for Developer and Reviewer
• thinking activity as it streams
• streaming text activity (bounded tail)
• tool lifecycle: start, running, completion, short errors
• final authoritative output token usage

A heartbeat keeps the elapsed time advancing even during silent stretches (for example model loading), and a still-running tool is named instead of letting the view look frozen. Streaming usage counters stay honest: volume is shown while generating, real token counts only once Pi reports them at message_end.

Optional image specialists

Capability	Model	Runtime
Generate	Z-Image-Turbo Q4_K	stable-diffusion.cpp
Edit	FLUX.2 Klein 4B Q4_0	stable-diffusion.cpp

Image specialists are stateless workers, not thinking roles: they receive only an asset spec and return an asset path plus metadata. They share the single-GPU lease, so only one local GPU workload runs at a time. Reference only, not required.

Reference runtime

Windows laptop, RTX 3070 Laptop GPU (8 GB VRAM), 16 GB RAM class, Pi 0.85.1.

Role	Model	Thinking
Architect	Qwen 3.5 9B (local-router/qwen35-9b)	high
Worker / developer	Qwen 3.5 9B	high
Reviewer	Qwen 3.5 9B	high

Optional local runtime: Qwen 3.6 35B-A3B (local-router/qwen36-35b-a3b, IQ4_XS, vision enabled, manual download, RTX 3060 12GB via CPU-MoE). No round router: fresh evidence goes straight to the Qwen3.6 Architect, which alone decides the next task (including visual need).

Commands

Command	Purpose
/agent-loop-setup	create missing loop config from bundled examples (never overwrites; reports mixed missing/write failures together, never a false done)
/agent-loop-start <workspace> <max> --team	arm the full Architect → Worker → Reviewer flow
/agent-loop-status	show current phase, task, role, attempt, and runner state
/agent-loop-stop	stop the current session loop
/agent-loop-team-models list	show configured/resolved/frozen Team models
/agent-loop-team-thinking list	show role thinking configuration
/agent-loop-image-models list	show optional image specialist profiles

Details: Command reference.

Tests

node ./tests/team.tests.mjs
node ./tests/package.tests.mjs
node ./tests/ledger.tests.mjs
node ./tests/phase.tests.mjs
node ./tests/develop.tests.mjs
node ./tests/work.tests.mjs
node ./tests/image.tests.mjs
node ./tests/creative-tools.tests.mjs
node ./tests/ledger.integration.tests.mjs
node ./tests/ledger.smoke.mjs
node ./tests/ledger.recovery.smoke.mjs
node ./tests/evidence.smoke.mjs

Validated with: Pi Git package install/remove, Qwen 3.5 9B real team runs to PASS, FAIL → repair → PASS, restart recovery, bounded long-run ledger simulation, real full-page browser evidence, a real long-page localhost:8010 smoke, live role streaming, and single-GPU specialist handoff.

Documentation

• Installation
• Ubuntu migration
• Configuration
• Command reference
• Team loop
• Reviewer contract
• Browser review
• Phase ledgers
• Architecture

Current status

Team loop with Architect → Worker → Reviewer to PASS/FAIL, Pi Git package install, headless Edge browser evidence with long-page coverage, Order/Phase Ledgers, live role progress, and Qwen 3.5 9B reference runs are implemented and smoke-tested against a real local website.

License

MIT — see LICENSE.