Install in one command

pi install npm:pi-rich-questions

If Pi is already running, run /reload; otherwise, start Pi interactively. Then try:

/rich-questions

[!TIP] That's it. There is nothing else you need to configure for automatic tool calls. You can stop reading and get back to work, or keep scrolling if you're curious.

See it in action

How it works

| 1. Pi asks | 2. You decide | 3. Pi continues | | :---: | :---: | :---: | | The model opens a rich form automatically, or you run /rich-questions. | Compare detailed choices, add notes, and review everything before submitting. | Pi receives every presented option, your selections, and your notes as one complete decision record. |

Two ways to use it

Automatic tool calls

In normal use, you don't need to do anything. The model can call ask_rich_questions when one or more questions deserve a structured form instead of plain text.

Manual trigger: /rich-questions

If the model asked questions in plain text, run /rich-questions to extract them from the latest completed assistant message and open the same form. In an empty session, it offers to send demo pi-rich-questions to the active agent.

Rich forms require Pi's interactive TUI. RPC, JSON, and print modes receive an actionable error instead of trying to open the custom component. A model provider is only needed for /rich-questions extraction; direct ask_rich_questions forms do not require a separate extraction call.

Version 0.4.0 is validated against Pi 0.84.4 and 0.85.x. Following Pi's package guidance, host-provided Pi modules are wildcard peers so newer Pi releases install normally; the exact development lock and compatibility matrix record what has been tested. Fullscreen mouse interaction is available on Pi hosts that expose normalized mouse events; keyboard operation remains complete on the minimum tested version.

Features

| | | | --- | --- | | 🔘 Ask the right wayRadio, checkbox, and freeform text questionsMultiple related questions in one formOptional and required fieldsSmart defaults and custom “Other” answers | 🎨 Keep the contextMarkdown prompts and explanationsRecommendations and caveatsDetailed option tradeoffsStable machine-readable values | | ✍️ Capture thoughtful answersPer-option response notesMultiline text and freeform notesReview before submissionEvery option and selection returned to Pi | 🖥️ Stay comfortable in the terminalLong-form and small-terminal scrollingFullscreen wheel and click supportConfigured keybinding-aware guidanceANSI and Unicode-safe widths |

• Question types: Radio, checkbox, and freeform text questions
• Multi-question: Multiple related questions in one form
• Markdown context: Rich formatting for prompts, recommendations, caveats, and option details
• Recommendations: Visual markers for suggested choices
• Field validation: Optional and required question settings
• Smart defaults: Pre-filled radio, checkbox, and text initial values
• Custom answers: Built-in "Other" option for custom user choices
• Option notes: Per-option user comments on predefined choices
• Multiline input: Text area editing and additional freeform notes
• Review screen: Summary step to inspect answers before submission
• Smart scrolling: Height-aware viewport for long forms and small terminals
• Fullscreen mouse: Wheel scrolling, clickable options/model rows, and editor cursor positioning on supported Pi hosts
• Configured keys: Semantic navigation and displayed guidance follow Pi keybindings
• Clean cancellation: Explicit cancellation handling without partial submission
• Complete record: Echoes every presented option, selection, and note back to the model
• Terminal formatting: ANSI and Unicode-safe display width handling
• Stable keys: Machine-readable option values separate from display labels

When it helps

Use Pi Rich Questions for decisions with meaningful explanation or several related inputs: deployment choices, review checklists, requirements gathering, migrations, or any prompt where a one-line clarification would discard useful detail.

[!NOTE] Plain chat is still better for a tiny, low-stakes question. Rich forms are most useful when the details affect the decision.

Quick configuration

The first time /rich-questions extracts an assistant message, choose either:

1. Session model with low extraction thinking (recommended). Pi clamps the level to model support.
2. A dedicated authenticated model with one of its supported thinking levels.

Use /rich-questions config to change the choice and /rich-questions reset to restore session-model/low-thinking behavior. If a dedicated model is unavailable or fails, extraction retries once with the current session model and session thinking. Pi's model runtime preserves provider-native dispatch, credentials, endpoints, headers, and environment. Extraction prefers a constrained internal tool call, retains JSON text parsing for provider compatibility, and preserves the complete assistant message in one broad multiline fallback question if all attempts fail.

Read Commands and configuration for storage, authentication, fallback, privacy, cost, and latency details.

Essential keys

You don't need to memorize these; it is very intuitive, and you can always press Ctrl+H inside the form whenever you want the built-in guide.

The table shows Pi's default bindings. Navigation, confirmation, cancellation, paging, submission, and newline hints follow your configured Pi keybindings.

| Key | Action | | --- | --- | | ↑ / ↓ | Move between options | | Enter | Select, continue, save an edit, or submit | | Space | Toggle a checkbox option | | N | Add or edit a response note for a predefined option | | Shift+Enter | Insert a newline in an editor | | Tab / Shift+Tab | Next / previous question | | PgUp / PgDn | Scroll the form ⭐️ | | Ctrl+H | Toggle the in-form guide | | Esc | Leave an editor; press again outside an editor to cancel | | Ctrl+C | Cancel immediately | | Mouse (fullscreen) | Wheel to scroll; click options or model rows; click editors to place the cursor |

The interaction and accessibility guide covers terminal behavior and the complete reference.

Documentation

| Start here | Go deeper | Project | | --- | --- | --- | | Getting startedAuthoring questionsCommands and configuration | Interaction and accessibilityResult contractTroubleshootingSecurity and privacy | ArchitectureDevelopmentReleasingChangelog |

Support and contributing

Search or open a GitHub issue for reproducible bugs and feature proposals. Read CONTRIBUTING.md before sending a pull request and SECURITY.md before reporting a vulnerability.