Limner

Limner is an agent-guided visual fidelity workbench. It helps a coding agent turn an input image into an approved HTML mockup, then compare that approved mockup against a real implementation.

Limner is model-agnostic. It does not call a vision model and it does not make final pass/fail judgments. It prepares artifacts and schemas for agent-authored UX comparison scores, diffs, and next-iteration guidance.

The older visual spec workflow is archived in docs/archive/visual-spec-workflow.md; active loops use DB-native agent comparison responses.

Install

Use the published CLI:

npm install -g @neonwatty/limner
limner --help

Or run it without a global install:

npx @neonwatty/limner --help

Install from source for development:

npm install
npm run build

Run from source during development:

npm run dev -- --help

After build:

node dist/cli.js --help

Run the full local gate before PRs:

npm run check

npm run check runs ESLint, TypeScript, Vitest, build, Knip, and a tracked-file line-count guard.

Basic Workflow

limner init ./ideal.png --target replay-boundaries
limner preview --target replay-boundaries
limner capture reference --target replay-boundaries
limner loop start --mode image-mockup --target replay-boundaries --name replay-boundaries-polish --max-iterations 5
limner loop compare --trajectory traj_...
limner loop task --trajectory traj_... --executor subagent
limner loop action start --trajectory traj_... --from-run run_... --kind polish --executor subagent --summary "Resize dashboard preview"
limner loop action complete --trajectory traj_... --action act_... --executor subagent --summary "Adjusted preview sizing" --files "src/app/page.tsx"
limner loop status --trajectory traj_...
limner compare image-reference --target replay-boundaries
limner compare reference-implementation --target replay-boundaries --url http://localhost:3152/internal/optimization-lab/wedding-envelope#replay-boundaries --storage-state ./e2e/.auth/user.json
limner report --target replay-boundaries
limner ledger export traj_... --format markdown
limner runs list

Workspace Shape

limner-workspace/
  limner.config.ts
  targets/
    replay-boundaries/
      source/ideal.png
      contract/regions.json
      contract/tokens.json
      contract/acceptance.md
      reference/index.html
      reference/styles.css
      captures/
      reports/
      AGENT_GUIDE.md
  .limner/runs/

Modes

Loop Ledger

Use limner loop for Ralph Loop-style polishing. Loop work is tracked in a global local-only SQLite ledger at ~/.limner/ledger.sqlite; no telemetry is sent.

limner loop start --mode image-mockup --target replay-boundaries --name replay-boundaries-polish --max-iterations 5
limner loop compare --trajectory traj_...
limner loop task --trajectory traj_... --executor subagent
limner loop action start --trajectory traj_... --from-run run_... --kind polish --executor subagent --summary "Resize dashboard preview"
limner loop action complete --trajectory traj_... --action act_... --executor subagent --summary "Adjusted preview sizing" --files "src/app/page.tsx"
limner loop action skip --trajectory traj_... --from-run run_... --summary "Comparison smoke only; no edit intended"
limner loop response submit --trajectory traj_... --from-run run_... --file ./response.json
limner loop status --trajectory traj_... --feedback "Prompt should mention button contrast."
limner loop next --trajectory traj_...
limner loop close --trajectory traj_...

Loop modes:

• image-mockup: source image to editable HTML mockup.
• mockup-implementation: approved mockup to real implementation.
• image-implementation: source image directly to real implementation.

Every meaningful loop interaction writes a ledger event. Agent responses are submitted into local SQLite with the full JSON body, response hash, validation status, and freshness (missing, fresh, stale, or invalid). agentFeedback is an optional 255-character field for short process-improvement notes; longer comments belong in notes or project artifacts.

Action Logging

After loop compare creates a comparison prompt, have the agent submit structured JSON with limner loop response submit --trajectory traj_... --from-run run_... --file ./response.json. Once the response validates, use limner loop task --trajectory traj_... --executor subagent to print the next edit brief. The intended loop is:

loop compare -> loop response submit -> loop task --executor subagent -> loop action start -> edit -> loop action complete -> loop compare

The task brief names likely files, selectors, prioritized diffs, next steps, action logging commands, and the compare command to rerun. Record loop action start before edits and loop action complete after edits; keep --summary under 255 characters. Use loop action skip for comparison-only smoke runs where no edit is intended. Limner records executor intent and action claims; it cannot prove an external orchestrator actually used a subagent. Use --format json when another tool needs machine-readable handoff data.

Use limner ledger to query and export trajectories:

limner ledger list --active
limner ledger status --trajectory traj_...
limner ledger show traj_...
limner ledger next --trajectory traj_...
limner ledger export traj_... --format json
limner ledger export traj_... --format markdown
limner ledger delete trajectory --trajectory traj_... --dry-run
limner ledger delete run --trajectory traj_... --run 2026-... --dry-run
limner ledger delete response --response resp_... --dry-run

Ledger deletes are dry-run by default. Pass --yes to actually delete matching local SQLite rows.

Agents can discover the current CLI surface with:

limner --help
limner loop --help
limner loop task --help
limner ledger --help

Image To Reference

Use this while recreating the ideal image as a standalone HTML/CSS mockup. This mode uses the ideal-to-mockup agent comparison profile.

limner compare image-reference --target replay-boundaries

Outputs:

• captures/image-reference/reference.png
• captures/image-reference/side-by-side.png
• captures/image-reference/agent-comparison/agent-prompt.codex.md
• captures/image-reference/agent-comparison/agent-response.schema.json
• reports/image-reference.md

In a loop trajectory, submit the agent's structured response with limner loop response submit --trajectory <trajectory-id> --from-run <run-id> --file ./response.json. Limner validates and emits:

• captures/image-reference/image-comparison.json
• captures/image-reference/comparison-summary.json

Agents should inspect the ideal image and reference screenshot separately. The side-by-side image is comparison context, not the source image to parse.

Reference To Implementation

Use this after the HTML mockup is approved and the real implementation needs to match it. This mode uses the mockup-to-implementation agent comparison profile.

limner compare reference-implementation --target replay-boundaries --url http://localhost:3152/... --storage-state ./e2e/.auth/user.json

Outputs:

• captures/reference-implementation/reference.png
• captures/reference-implementation/implementation.png
• captures/reference-implementation/side-by-side.png
• captures/reference-implementation/dom-metrics.json
• captures/reference-implementation/agent-comparison/agent-prompt.codex.md
• captures/reference-implementation/agent-comparison/agent-response.schema.json
• reports/reference-implementation.md

In a loop trajectory, submit the agent's structured response with limner loop response submit --trajectory <trajectory-id> --from-run <run-id> --file ./response.json. Limner validates and emits:

• captures/reference-implementation/image-comparison.json
• captures/reference-implementation/structure-comparison.json
• captures/reference-implementation/comparison-summary.json

Capture commands default to viewport-only screenshots. Add --full-page when the full scrollable page is the comparison target.

Local Logs

Limner writes local structured logs only. There is no remote telemetry.

.limner/runs/<run-id>/
  manifest.json
  events.jsonl
  agent-notes.md

Use:

limner runs list
limner runs show <run-id>
limner runs summarize