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...