User Guide

Install

From the repository root:

uv sync

Run a safe dry-run with the loop CLI:

uv run loop run specs/code-fix-loop.yaml

Dry-run is the default. It renders the workflow, prompt artifacts, and command plan without calling an agent or running shell commands.

Launch from markdown

Create a loop file:

# Fix Login Bug
mode: deterministic
goal: Fix the login regression and prove it with tests.
max_iterations: 3

## Flow
- coder: prompt prd/02_coder.md -> pass: verifier, fail: failed
- verifier: command `uv run pytest tests/test_login.py` -> pass: success, fail: coder

Launch it:

uv run loop launch fix-login.loop.md

Execute it only after reviewing the generated artifacts:

uv run loop launch fix-login.loop.md --execute

Compile without running:

uv run loop compile fix-login.loop.md

Markdown loop shape

Use a markdown heading for the title, then simple key: value metadata:

Field	Required	Meaning
goal	Yes	What the loop should accomplish.
mode	No	loose, in-depth, or deterministic.
max_iterations	No	Hard cap that prevents runaway loops.
check	Sometimes	Verifier command used by preset flows.

Add ## Flow when you want an explicit route graph. Each flow line has this shape:

- step-name: prompt path/to/prompt.md -> pass: next-step, fail: repair-step
- step-name: command `shell command` -> pass: success, fail: previous-step

Preset modes

Mode	Generated workflow	Needs check:?
loose	worker prompt only	No
in-depth	planner -> coder -> reviewer, plus verifier when check: is set	No
deterministic	planner -> coder -> verifier	Yes

Use loose for exploratory tasks, in-depth for feature work that benefits from review, and deterministic when a verifier command defines done.

Output files

LoopKing writes local artifacts so you can inspect what happened:

.loopspec/generated/<name>.yaml       # compiled markdown loop (LoopSpec format)
.loopspec/prompts/<name>/*.md         # generated preset prompts
runs/<stamp>-<name>/state.json        # resumable run state
runs/<stamp>-<name>/*.prompt.md       # rendered prompt artifacts
runs/<stamp>-<name>/*.out.md          # prompt-agent output in execute mode
runs/<stamp>-<name>/*.log             # command output in execute mode
runs/<stamp>-<name>/final_report.md   # final status report

Team layer (LoopKing Cloud)

The open-source loop CLI stays local-first. LoopKing Cloud (at loopk.ing) adds an optional hosted team layer for sharing loops, tool profiles, and run history. Configure it with a loopking.yaml at your repo root:

team: acme
registry:
  backend: http
  base_url: https://api.loopk.ing
profiles:
  default:
    skills: [code-review, debugging]
    commands: [uv run pytest]
    policies:
      require_approval: [deploy, database_write]

The registry token is read from $LOOPKING_TOKEN and is never stored in the file.

Share and reuse loops:

loop registry push fix-login.loop.md   # publish a versioned loop
loop registry list                     # list shared loops
loop registry pull fix-login --dest .  # fetch a shared loop

Sync your team's agent tooling (skills, MCP servers, verifier commands, policies) into a local .loopking/ directory:

loop tools list                        # profiles defined in loopking.yaml
loop tools show default                # resolved profile contents
loop tools sync --profile default      # materialize the profile locally

Upload privacy-preserving run metadata (status, step outcomes, and an artifact manifest of names/sizes/checksums - never source or contents):

loop runs push runs/<stamp>-<name>     # upload one run's metadata
loop runs list <spec-name>             # list uploaded runs for a spec

Safety notes

• Markdown loop files are trusted workflow inputs.
• Command steps run only with --execute.
• Dry-run every new loop before executing it.
• Prompt files, working directories, run roots, and custom output paths are kept inside the markdown directory boundary.
• Generated .loopspec/ files and synced .loopking/ state are local artifacts and ignored by Git.
• Prefer verifier commands that prove the user-visible behavior, not just formatting or imports.