agentloupe — Loop engineering

A agentic layout tool: write a structured spec, get pixel-perfect HTML+CSS that an agent can iterate on.

Loop engineering — name-coined from agentloupe (agent + loupe = the magnifying glass an agent uses to look at and fix layouts). The pun works in both English ("agent's loupe") and Japanese (エージェント + ループ = "agent that loops / loop engineering").

What it is

• Spec-first: a small YAML/JSON spec describes a layout.
• Browser-rendered: outputs static HTML+CSS — the browser paints it, no headless setup required.
• Iterative: agentloupe watch re-renders on save. Edit the spec, refresh the browser.
• LLM-friendly: agentloupe schema emits canonical JSON Schema (draft 2020-12) for tool definitions.
• Boring dependencies: Node.js 18+ only. Three runtime deps (yaml, chokidar, commander).

What it is not

• Not a Tailwind/sass/CSS framework. It outputs plain HTML+CSS strings.
• Not a server-side rendering tool. Use the static HTML.
• Not a pixel-perfect rasterizer. Use pailow for that.
• Not a state manager. The browser takes care of interactions.

Install

npm install -g agentloupe
# or, with bun:
bun install -g agentloupe

agentloupe requires Node.js 18+ at runtime. The CLI binary is at dist/cli.js after npm install / bun install.

Quick start

# Start from the canonical preset
agentloupe new --preset card

# Validate
agentloupe validate loupe.yml

# Render to HTML
agentloupe render loupe.yml -o index.html

# Watch + re-render in browser
agentloupe watch loupe.yml
# open ./loupe.out.html in any browser, refresh on each save

# Print the LLM-facing JSON Schema
agentloupe schema --json

Spec at a glance

layers:
  - type: box
    grid: { cols: 12, col: 1, span: 4 }
    background: "#ffffff"
    box_shadow: 0px 8px 24px 0px rgba(0, 0, 0, 0.08)

  - type: box
    grid: { cols: 12, col: 5, span: 8 }
    children:
      - type: heading
        text: "Built for the front-end engineer agent."
      - type: link
        text: "Try it"
        href: "/start"

Layer types: box, heading, paragraph, link, image, input, list. See agentloupe schema --md for the full reference.

Iterating with an agent

# Terminal A: starts watch
agentloupe watch examples/card.loupe.yml

# Terminal B: the agent edits the spec
$EDITOR examples/card.loupe.yml
# save → watch re-renders → reload browser

# Validate the agent's output
agentloupe validate examples/card.loupe.yml --json

Natural language corrections are LLM's job. agentloupe just renders.

Philosophy

• spec-first: output is fully determined by the spec. No hidden state.
• container-friendly: Node.js 18+ only, no DB, no Docker images.
• LLM contract: the JSON Schema is the spec. Don't fork the schema.
• early valid / early fail: validation collects every error in one pass.
• minimal deps: 3 runtime deps, no native bindings.
• byte-stable rendering: same spec → same HTML, byte-identical.

Companion

agentloupe is the layout sibling of pailow (the image-overlay CLI). They share the same spec-first philosophy but produce different outputs:

• pailow: JSON → Pillow → PNG (byte-stable, deterministic)
• agentloupe: YAML/JSON → TypeScript → HTML+CSS (browser-rendered, iterative)

For PNG output, use pailow. For HTML output, use agentloupe.

License

MIT