pi-forms

A reusable show_form tool for pi agents. Agents call the tool with a declarative form schema, an interactive TUI overlay pops up for the user to fill in, and the collected values are returned as JSON.

Installation

Project-local (recommended):

# From your project root
cp -r pi-forms .pi/extensions/pi-forms

Global:

cp -r pi-forms ~/.pi/agent/extensions/pi-forms

Quick test:

pi -e ./pi-forms

Supported Field Types

Type	Description	Input
input	Single-line text	Type normally, Enter to advance
select	Pick one from a list	↑↓ to navigate, Enter to advance
multiselect	Pick multiple from a list	↑↓ to navigate, Space to toggle, Enter to advance
editor	Multi-line text	Type normally, Enter for newline
toggle	Two-state toggle (defaults to Yes/No)	←→ or Space to toggle

Note: Every form automatically includes Cancel and Submit buttons at the bottom.

Example Tool Call

An agent can call the tool like this:

show_form({
  title: "Create Bug Report",
  description: "Fill in the details below",
  fields: [
    { name: "summary",     type: "input",   label: "Summary",     required: true },
    { name: "severity",    type: "select",      label: "Severity",    options: ["High", "Medium", "Low"] },
    { name: "components",  type: "multiselect", label: "Components",  options: ["API", "UI", "Auth", "DB"] },
    { name: "description", type: "editor",  label: "Description", placeholder: "Describe the bug..." },
    { name: "environment", type: "input",       label: "Environment", defaultValue: "production" }
  ]
})

The form will automatically show Cancel and Submit buttons at the bottom.

What the Agent Gets Back

{
  "summary": "Login fails for Okta athletes",
  "severity": "High",
  "components": ["API", "Auth"],
  "description": "When an Okta athlete attempts to authenticate...",
  "environment": "production"
}

Or if cancelled: "User cancelled the form."

Keyboard Navigation

Key	Action
Tab / Shift+Tab	Cycle between fields and buttons
Enter	Advance to next field; activate focused button
↑↓ or ←→	Navigate select options / toggle / switch buttons
Space	Toggle multiselect/toggle fields; activate focused button
Ctrl+S	Submit the form
Esc	Cancel and return to agent

Field Options

Property	Type	Required	Description
name	string	✓	Unique key in the returned JSON
type	string	✓	input, select, multiselect, editor, or toggle
label	string	✓	Label displayed to the user
required	boolean		If true, field must be filled to submit
placeholder	string		Placeholder for empty input fields
defaultValue	string		Pre-filled value
options	string[]		Options for select/multiselect fields, or two labels for toggle (e.g. ["On", "Off"])

Test Prompt

After installing, paste this into the pi chat window to exercise all field types:

Use the show_form tool to collect a bug report with these fields:

 - summary (required, single-line text)
 - severity (required, pick one: Critical, High, Medium, Low)
 - components (pick multiple: API, UI, Auth, Database, DevOps)
 - description (multi-line text)
 - steps to reproduce (multi-line text)
 - environment (pick one: Production, Staging, Dev)
 - is regression (yes/no)

Read what the user entered and print a full bug report.

Using with Agents

Add show_form to an agent's tool list so it can pop up forms during conversations:

---
name: bug-reporter
tools: show_form, jira_create_issue
---
You are a bug reporting assistant. Use show_form to collect bug details...