formloop

Let your AI agent ask humans complex questions with real UI — not chat.

When an LLM agent needs structured input from a human, chat breaks down. formloop generates Typeform-quality forms on-the-fly — with clickable mockups, sliders, drag-and-drop — sends a link, and returns structured answers when the human submits.

One package. Works as an MCP server (Claude Code, Cursor, Windsurf), a CLI (Codex, custom agents), or a standalone HTTP server.

Install

MCP server (Claude Code / Cursor)

npx formloop install

This adds formloop to your MCP settings. Restart your editor — the create_form, wait_for_response, and list_submissions tools are now available.

CLI (Codex / bash agents)

# Create a form
npx formloop create --spec '{
  "title": "Pick a design",
  "blocks": [
    {"kind": "html-pick", "id": "hero", "title": "Which hero layout?",
     "options": [
       {"id": "a", "label": "Minimal", "html": "<div style=\"padding:2rem;background:#f0f0f0\"><h1>Clean</h1></div>"},
       {"id": "b", "label": "Bold",    "html": "<div style=\"padding:2rem;background:#6366f1;color:white\"><h1>Bold</h1></div>"}
     ]},
    {"kind": "rank", "id": "priorities", "title": "Rank these",
     "options": ["Speed", "Quality", "Cost"]}
  ]
}'

# Wait for the human to submit
npx formloop wait --form-id <ID>
# → { "answers": { "Which hero layout?": "a", "Rank these": ["Quality", "Speed", "Cost"] } }

Standalone server

npx formloop              # starts on http://127.0.0.1:3847
npx formloop --port 4000  # explicit port

How it works

Agent                          formloop                         Human
  │                               │                               │
  ├── create_form(spec) ─────────►│                               │
  │◄── { form_id, form_url } ────┤                               │
  │                               │                               │
  ├── (sends form_url to human) ──┼──────────────────────────────►│
  │                               │                               │
  │                               │◄── human fills form ──────────┤
  │                               │    clicks Submit              │
  │                               │                               │
  ├── wait_for_response(id) ─────►│                               │
  │◄── { answers } ──────────────┤                               │

The server runs locally — no cloud, no API keys, no data leaves your machine.

Question types

Kind	Description	Answer type
mc	Multiple choice (single select)	string
multi	Checkboxes (multi-select)	string[]
text	Short text input	string
textarea	Long text input	string
yn	Yes / No	boolean
number	Numeric input	number
scale	1-N scale	number
html-pick	Clickable HTML cards (mockups, designs)	string or string[]
rank	Drag-and-drop ordering	string[]
scale-preview	Slider with live HTML preview	number
html	Rich HTML context (no answer, display-only)	—
group	Multiple questions on one slide	—

Form spec reference

{
  "title": "Form title",
  "description": "Optional subtitle",
  "layout": "stack",
  "persistent": false,
  "blocks": [
    {
      "kind": "mc",
      "id": "q1",
      "title": "Pick one",
      "options": ["A", "B", "C"],
      "headerHtml": "<p>Optional HTML context above the question</p>"
    },
    {
      "kind": "html",
      "html": "<div>Context-only slide — no answer collected</div>"
    }
  ]
}

layout: "stack" (default, single column) or "split" (two-column: context left, answer right).

persistent: false (default) = single response, auto-deleted after retrieval. true = multi-response, permanent, with list_submissions support.

Self-hosting

formloop runs locally with zero configuration — no Redis, no cloud services needed. Data is stored in-memory.

npx formloop

For production or shared deployments, set these environment variables to use Upstash Redis:

KV_REST_API_URL=https://...    # Upstash Redis REST URL
KV_REST_API_TOKEN=...          # Upstash Redis REST token
WEBHOOK_SECRET=...             # Optional API auth secret

MCP tools

When running as an MCP server (npx formloop --mcp), three tools are exposed:

Tool	Description
create_form	Create a form from a spec. Returns { form_id, form_url }. Auto-opens in browser.
wait_for_response	Poll until an ephemeral form is submitted. Returns { answers }.
list_submissions	List all submissions for a persistent form.

CLI reference

formloop [options]              Start the HTTP server
formloop --mcp                  Start as MCP server (stdio transport)
formloop install                Add MCP config to Claude Code / Cursor
formloop create --spec '{...}'  Create a form
formloop wait --form-id <ID>    Poll until form is submitted
formloop list --form-id <ID>    List submissions (persistent forms)

Why formloop

	Chat	AskUserQuestion	Tally / Typeform	formloop
Rich UI (sliders, drag-and-drop, mockups)	No	No	No	Yes
HTML/SVG embedded as context	No	No	No	Yes
Async (respond from phone)	No	No	Yes	Yes
Generated by code	Yes	Yes	No	Yes
Multi-input structured	No	Limited	Yes	Yes
Free, self-hostable	Yes	Yes	No	Yes
Local-first (no cloud)	Yes	Yes	No	Yes

Related projects

• HumanLayer — orchestration for human-in-the-loop agents (Slack/Email/Discord). Complementary.
• Anthropic Artifacts — synchronous rich UI inside Claude.ai. formloop is async, agent-driven.

Contributing

See CONTRIBUTING.md.

License

MIT