nicobailon/pi-interview-tool

What it solves

When an agent needs clarification from a user, it often has to ask questions inline, which can be clumsy. This tool turns that into a dedicated, interactive form: it lets the agent present structured questions with rich context, gather answers at the user's own pace, and receive structured results back. It handles interruptions gracefully, saves progress automatically, and lets users recover abandoned or timed-out sessions.

How it works

The agent invokes the tool via an interview() function, passing a JSON file that defines the questions. The tool starts a local server and opens a form in a native Glimpse window on macOS (or a browser tab elsewhere). The user fills out the form, with auto-save to localStorage and a countdown timer that resets on any activity. When the user submits, the responses are returned to the agent; if cancelled or timed out, the agent gets null. The tool also supports multiple concurrent interviews: only the first one opens a window automatically, while others are queued to avoid stealing focus. If the session is remote (ssh/mosh), the tool prints the form URL with access hints instead of opening a local window. Timeout and abandoned interviews save their questions to a recovery directory for later retry.

Who it's for

Developers and users working with pi-agent who need to collect structured, interactive feedback from a live user — for example, clarifying project requirements, gathering preferences, or reviewing options during an agent-driven workflow. It's especially useful when an agent needs to ask a series of questions with rich context like code snippets, diagrams, or tables.

Highlights

• Supports single-select, multi-select, text, image upload, and info panels — with keyboard navigation throughout
• Embeds rich media directly in questions: images, Chart.js charts, Mermaid diagrams, tables, and raw HTML
• Recommendations with configurable conviction (strong/slight) and visual weight (critical/minor) to guide decisions
• Auto-save to localStorage and session timeout with warning overlay; progress is never lost accidentally
• Session recovery: abandoned or timed-out interviews are saved to a recovery folder and can be retried later
• Multi-agent support: concurrent interviews queue instead of fighting for the window, with a toast switcher for queued sessions
• LLM-powered "Generate more" and "Review options" buttons can create new choices or rewrite the question for clarity
• "Ask about an option" opens an inline assistant panel with prompt chips and freeform follow-up questions
• Customizable themes (dark/light/auto) with user-defined CSS overrides and a toggle hotkey
• Launcher selection: open forms in Glimpse, a browser tab, or an Orca-managed browser tab

How it works

Here is a quick overview of the flow (more details are in the README):

1. The agent calls interview() with a questions JSON file.
2. A local server starts and the form opens in the chosen launcher (Glimpse, browser, or Orca).
3. The user answers at their own pace; every change auto-saves and resets the timeout.
4. On submit, the responses are sent back to the agent. On cancel or timeout, the agent receives null (or the tool can return an interview ID for async delivery).
5. If the session is remote (ssh/mosh), the tool prints the form URL and access hints instead of opening a local window.

Lifecycle

• Submit (⌘+Enter): responses returned to the agent.
• Timeout: a countdown badge resets on any activity; when it expires, a warning overlay lets the user continue or close.
• Escape × 2: quick cancel.

Session Recovery

If an interview times out or is abandoned (tab closed, lost connection), the questions are saved to ~/.pi/interview-recovery/ with a filename like 2026-01-02_093000_myproject_main_65bec3f4.json. You can retry later by passing that file to interview(). Files older than 7 days are auto-cleaned.

Multi-Agent Behavior

When multiple agents run interviews simultaneously, only the first auto-opens the window. Subsequent interviews are queued and shown as a URL in the tool output. Submitting the active interview automatically redirects to the next queued one. A top-right toast with a dropdown lets you open queued sessions. A session status bar shows project path, git branch, and session ID for identification.

Timeout Behavior

The countdown (visible in the corner) resets on any activity — typing, clicking, or mouse movement. When it expires, an overlay appears giving the user a chance to continue. Progress is never lost thanks to localStorage auto-save.

Who it’s for

Developers building or using pi-agent workflows that require interactive user input. It’s ideal for situations where an agent needs clarification on project details, preferences, design decisions, or other parameters — and where a structured form is more reliable than free-form chat. Also useful for teams that need to collect feedback consistently and recover from interruptions.

Highlights

• Rich Question Types: single-select, multi-select, text input, image upload/camera capture, and info panels.
• Embedded Media: images, Chart.js charts, Mermaid diagrams, tables, and HTML inside questions.
• Recommendations with Conviction & Weight: control how strongly options are suggested and their visual prominence.
• Auto-save & Timeout Recovery: responses are saved to localStorage; abandoned/timeout interviews are recoverable.
• Multi-Agent Support: concurrent interviews queue instead of stealing focus, with a toast switcher.
• LLM-Powered Helpers: generate more options or review/rewrite questions with a configurable model.
• Ask About an Option: inline assistant panel with prompt chips and freeform follow-up questions.
• Theming: dark/light/auto themes plus custom CSS overrides and a toggle hotkey.
• Launcher Options: choose Glimpse, browser, or Orca for displaying the form.
• Keyboard Navigation: full keyboard support including shortcuts for navigation, selection, and submission.