Formloop

Skill formloop

formloop lets you generate a Typeform-quality form on-the-fly, ask a human structured questions, and resume execution when the form is submitted. The missing layer when AskUserQuestion saturates and chat is the wrong UI.

100% local. Server runs on 127.0.0.1:3847. No accounts, no cloud, no telemetry.

When to use formloop (vs alternatives)

Bootstrap (once per session)

Check that the server is up, otherwise start it. npx formloop boots a Next.js server on 127.0.0.1:3847 and auto-builds on first run.

# Verify
curl -s -m 2 http://127.0.0.1:3847/ -o /dev/null && echo "up" || echo "down"

# Start (one-line, no deps to install — the bin does it)
npx formloop

In Claude Code: run npx formloop via Bash run_in_background: true, then poll for readiness with until curl -s -m 2 http://127.0.0.1:3847/ -o /dev/null; do sleep 1; done.

Ephemeral mode (1 respondent, urgent decision)

# 1. Create the form (auto-opens in browser unless --no-open)
npx formloop create --spec '{
  "title": "Hero design direction",
  "blocks": [
    {"kind": "html-pick", "id": "design", "title": "Which direction?",
     "options": [
       {"id": "a", "label": "Minimal", "html": "<div style=\"...\">Mockup A</div>"},
       {"id": "b", "label": "Bold",    "html": "<div style=\"...\">Mockup B</div>"}
     ]},
    {"kind": "textarea", "id": "notes", "title": "Any notes?", "required": false}
  ]
}'

# 2. Wait for submission (run in background so the conversation auto-resumes)
npx formloop wait --form-id <ID> --timeout 1800

Output of wait:

{
  "form_id": "ABC123",
  "answers": {
    "Which direction?": "b",
    "Any notes?": "Looks great"
  },
  "submitted_at": "2026-05-26T15:00:00.000Z"
}

Persistent mode (N respondents — audit, panel, survey)

npx formloop create --spec '{
  "title": "SAV rules audit — Batch 1",
  "persistent": true,
  "respondentField": {
    "type": "email-name",
    "required": true,
    "intro": "Your first name and email, so we can compare answers across reviewers"
  },
  "blocks": [
    {"kind": "html",
     "html": "<h2>Why this form?</h2><p>We audit ~80 SAV rules to identify critical / secondary / drop. Your input compared to others shows where we agree and where we don'''t.</p>"},
    {"kind": "html",
     "html": "<div style=\"padding:16px;background:#f4f4f8;border-radius:8px\"><strong>Rule 1 — Dates</strong><br><br>NEVER give a past date as future date.<br>❌ \"shipping 21/04\" when we'''re 25/04<br>✅ \"shipping within 2-3 business days\"</div>"},
    {"kind": "mc", "id": "rule1_decision", "title": "Rule 1 — Action?",
     "options": ["Keep as-is", "Amend", "Drop"]},
    {"kind": "textarea", "id": "rule1_comment", "title": "Rule 1 — Notes",
     "required": false},
    {"kind": "mc", "id": "rule1_importance", "title": "Rule 1 — Importance",
     "options": ["Critical", "Important", "Secondary", "Not sure"]}
  ]
}'

Then:

# Share the same URL with N respondents (email/Slack/etc).
# List all submissions at any time:
npx formloop list --form-id ABC123

# Or block until N submissions are in:
# (not yet in the bin — use the Python SDK: ask_form.py wait-n)

Block types

All embedded HTML is sanitized via DOMPurify server-side. <script>, event handlers, and iframes are stripped. SVG is allowed (charts, illustrations).

respondentField — capture identity (persistent only)

"respondentField": {
  "type": "email-name",
  "required": true,
  "intro": "Your first name and email"
}

Effect: Formloop renders 2 fields (first name + email) at the very start of the form. Each submission then includes respondent: {name, email} alongside answers.

Best practices

For multi-respondent (audit, panel):

• persistent: true is mandatory — otherwise only the first respondent counts.
• respondentField: email-name unless you really want anonymous.
• Keep under 30 blocks. Beyond, drop-off explodes. Split big audits across thematic forms.
• Frame each item to audit with an html block that renders the item verbatim (title + ✅/❌ + real example) before the decision questions. Respondents shouldn't need to scroll a .md side-by-side.
• For diffusion: email/Slack with a clear intro — why this form, estimated time, how results are used.

For ephemeral (1 decision):

• Cap at 6-8 blocks.
• Prefer html-pick over mc when the choice is visual.
• Use html blocks as intros, not description, when you want rich HTML.

For both:

• Explicit titles: "Hero design direction" beats "A few questions".
• required: false on free-form textarea comments.
• Test the form URL yourself before sending it.

Limitations

• No conditional logic (skip-if/else). All questions are seen by all respondents.
• No mid-form computation. Aggregate after submission.
• HTML sanitization is strict. Use scale-preview for interactivity.
• Spec TTL 24h, ephemeral response TTL 1h. Restart of the local server wipes everything (in-memory store).
• No push notifications to respondents — sending email/Slack is on the caller.
• 1 form = 1 spec. To iterate, create a new form (the old one stays accessible).

Self-hosting

By default, npx formloop runs entirely on 127.0.0.1:3847 with an in-memory store. If you want persistence across restarts, set KV_REST_API_URL + KV_REST_API_TOKEN to point at an Upstash Redis (or any Upstash-compatible KV).

To require API auth (multi-user shared server), set WEBHOOK_SECRET=<long-random-string> and pass it as the x-webhook-secret header on every /api/forms* call.