ask-user-question — Interactive Form Tool for pi

A pi extension that registers a tool the LLM can call to ask the user structured questions using rich form controls: radio buttons, checkboxes, and text inputs.

Instead of the LLM asking questions in plain text and waiting for a freeform response, this tool presents an interactive TUI form where each question is typed, validated, and returned as structured data.

How It Works

1. LLM calls the tool — Passes a JSON schema of questions with types, options, and metadata.
2. Form renders — An interactive panel appears in the terminal with typed controls for each question.
3. User answers — Navigate between questions, select options, type text, toggle checkboxes.
4. Structured return — Answers are returned to the LLM in a clean, structured format.

Question Types

Radio (single-select)

 ❯ ◉ PostgreSQL
   ○ MySQL
   ○ SQLite
   ○ Other...

Pick exactly one option. Press Enter to select. The "Other..." option opens a text editor for a custom answer.

Checkbox (multi-select)

 ❯ ☑ Unit tests
   ☑ Integration tests
   ☐ E2E tests
   ☐ Other...

Toggle multiple options with Space. The "Other..." option opens a text editor. Press Enter to advance.

Text (free input)

 ┌─────────────────────────────────┐
 │ Describe the migration strategy │
 └─────────────────────────────────┘

A full multi-line editor. Shift+Enter for newlines, Enter to submit.

Tool Schema

{
  "title": "Project Setup",
  "description": "Let me configure the project based on your preferences",
  "questions": [
    {
      "id": "database",
      "type": "radio",
      "prompt": "Which database should we use?",
      "label": "Database",
      "options": [
        { "value": "postgres", "label": "PostgreSQL", "description": "Best for complex queries" },
        { "value": "mysql", "label": "MySQL", "description": "Widely supported" },
        { "value": "sqlite", "label": "SQLite", "description": "Lightweight, file-based" }
      ],
      "allowOther": true
    },
    {
      "id": "testing",
      "type": "checkbox",
      "prompt": "Which test types should we set up?",
      "label": "Testing",
      "options": [
        { "value": "unit", "label": "Unit tests" },
        { "value": "integration", "label": "Integration tests" },
        { "value": "e2e", "label": "E2E tests" }
      ],
      "allowOther": true
    },
    {
      "id": "notes",
      "type": "text",
      "prompt": "Any additional notes or requirements?",
      "label": "Notes",
      "required": false,
      "placeholder": "Type any extra context here..."
    }
  ]
}

Question Fields

| Field | Type | Default | Description | | ------------- | --------------------------------- | ---------------------- | ----------------------------------------------------- | | id | string | required | Unique identifier | | type | "radio" | "checkbox" | "text" | required | Control type | | prompt | string | required | The question text | | label | string | Q1, Q2... | Short label for tab bar | | options | Option[] | [] | Choices for radio/checkbox | | allowOther | boolean | true (radio/checkbox) | Show "Other..." option with text input | | required | boolean | true | Must be answered before submit | | placeholder | string | — | Placeholder text for text inputs | | default | string | string[] | — | Default value(s) |

Option Fields

| Field | Type | Description | | ------------- | -------- | ---------------------------------- | | value | string | Value returned to the LLM | | label | string | Display label | | description | string | Help text shown below the label |

Panel Interface

Single Question

──────────────────────────────────────────────────────
 Which database should we use? [single-select]
 *required

 ❯ ◉ PostgreSQL
      Best for complex queries
   ○ MySQL
      Widely supported
   ○ SQLite
      Lightweight, file-based
   ○ Other...

 ↑↓ navigate • Enter select • Esc cancel
──────────────────────────────────────────────────────

Multiple Questions (tab bar)

──────────────────────────────────────────────────────
 Project Setup
 Let me configure the project based on your preferences

 ✓ Database │· Testing │· Notes │✓ Submit

 Which test types should we set up? [multi-select]
 *required

 ❯ ☑ Unit tests
   ☑ Integration tests
   ☐ E2E tests
   ☐ Other...

 ↑↓ navigate • Space toggle • Tab/←→ navigate • Enter next • Esc cancel
──────────────────────────────────────────────────────

Submit Tab (review)

──────────────────────────────────────────────────────
 ✓ Database │✓ Testing │✓ Notes │✓ Submit

 Review & Submit

 Database: PostgreSQL
 Testing: unit, integration
 Notes: Focus on API layer first

 Press Enter to submit

 Tab/←→ navigate questions • Enter submit • Esc cancel
──────────────────────────────────────────────────────

Keyboard Reference

Navigation

| Key | Action | | ----------------- | ------------------------------------- | | Tab / → | Next question (multi-question mode) | | Shift+Tab / ← | Previous question | | ↑ / ↓ | Navigate options within a question |

Selection

| Key | Action | | ----------------- | ------------------------------------- | | Enter | Select radio option / advance / submit | | Space | Toggle checkbox option | | Enter (text) | Submit text answer | | Shift+Enter | Newline in text/other editor |

Other

| Key | Action | | ----------------- | ------------------------------------- | | Esc | Cancel (in "Other" mode: go back) |

Output Format

The tool returns structured text to the LLM:

Database: PostgreSQL
Testing: unit, integration, (wrote) GraphQL tests
Notes: Focus on API layer first

Custom "Other" answers are prefixed with (wrote) so the LLM knows they were user-typed.

System Prompt Integration

The tool includes promptSnippet and promptGuidelines so the LLM knows when and how to use it:

• Prefers ask_user_question over plain-text questions
• Uses radio for single-choice, checkbox for multi-choice, text for open-ended
• Groups related questions in a single call
• Includes "Other" escape hatches by default

Dependencies

| Package | Role | | ------------------------------- | ------------------------------------------------- | | @earendil-works/pi-coding-agent | Extension API, theme types | | @earendil-works/pi-tui | TUI primitives: Editor, Key, matchesKey, etc. | | @earendil-works/pi-ai | StringEnum for Google-compatible enum schemas | | @sinclair/typebox | JSON Schema definitions for tool parameters |