Interview Tool

A custom tool for pi-agent that opens a web-based form to gather user responses to clarification questions.

interview-demo-sped-up.mp4

Installation

pi install npm:pi-interview

Restart pi to load the extension.

Requirements:

• pi-agent v0.35.0 or later (extensions API)

Features

• Question Types: Single-select, multi-select, text input, and image upload
• "Other" Option: Single/multi select questions support custom text input
• Per-Question Attachments: Attach images to any question via button, paste, or drag & drop
• Keyboard Navigation: Full keyboard support with arrow keys, Tab, Enter
• Auto-save: Responses saved to localStorage, restored on reload
• Session Timeout: Configurable timeout with countdown badge, refreshes on activity
• Multi-Agent Support: Queue detection prevents focus stealing when multiple agents run interviews
• Queue Toast Switcher: Active interviews show a top-right toast with a dropdown to open queued sessions
• Session Recovery: Abandoned/timed-out interviews save questions for later retry
• Save Snapshots: Save interview state to HTML for later review or revival
• Session Status Bar: Shows project path, git branch, and session ID for identification
• Image Support: Drag & drop anywhere on question, file picker, paste image or path
• Path Normalization: Handles shell-escaped paths (\ ) and macOS screenshot filenames (narrow no-break space before AM/PM)
• Themes: Built-in default + optional light/dark + custom theme CSS

How It Works

┌─────────┐      ┌──────────────────────────────────────────┐      ┌─────────┐
│  Agent  │      │              Browser Form                │      │  Agent  │
│ invokes ├─────►│                                          ├─────►│receives │
│interview│      │  answer → answer → attach img → answer   │      │responses│
└─────────┘      │     ↑                                    │      └─────────┘
                 │     └── auto-save, timeout resets ───────┤
                 └──────────────────────────────────────────┘

Lifecycle:

1. Agent calls interview() → local server starts → browser opens form
2. User answers at their own pace; each change auto-saves and resets the timeout
3. Session ends via:
   • Submit (⌘+Enter) → responses returned to agent
   • Timeout → warning overlay, option to stay or close
   • Escape × 2 → quick cancel
4. Window closes automatically; agent receives responses (or null if cancelled)

Timeout behavior: The countdown (visible in 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.

Multi-agent behavior: When multiple agents run interviews simultaneously, only the first auto-opens the browser. Subsequent interviews are queued and shown as a URL in the tool output, preventing focus stealing. Active interviews also surface a top-right toast with a dropdown to open queued sessions. A session status bar at the top of each form shows the project path, git branch, and session ID for easy identification.

Usage

The interview tool is invoked by pi-agent, not imported directly:

// Create a questions JSON file, then call the tool
await interview({
  questions: '/path/to/questions.json',
  timeout: 600,  // optional, seconds (default: 600)
  verbose: false // optional, debug logging
});

Question Schema

{
  "title": "Project Setup",
  "description": "Optional description text",
  "questions": [
    {
      "id": "framework",
      "type": "single",
      "question": "Which framework?",
      "options": ["React", "Vue", "Svelte"],
      "recommended": "React"
    },
    {
      "id": "features",
      "type": "multi",
      "question": "Which features?",
      "context": "Select all that apply",
      "options": ["Auth", "Database", "API"],
      "recommended": ["Auth", "Database"]
    },
    {
      "id": "notes",
      "type": "text",
      "question": "Additional requirements?"
    },
    {
      "id": "mockup",
      "type": "image",
      "question": "Upload a design mockup"
    }
  ]
}

Question Fields

Field	Type	Description
id	string	Unique identifier
type	string	single, multi, text, or image
question	string	Question text
options	string[] or object[]	Choices (required for single/multi). Can be strings or { label, code? } objects
recommended	string or string[]	Highlighted option(s) with * indicator
context	string	Help text shown below question
codeBlock	object	Code block displayed below question text

Code Blocks

Questions and options can include code blocks for displaying code snippets, diffs, and file references.

Question-level code block (displayed above options):

{
  "id": "review",
  "type": "single",
  "question": "Review this implementation",
  "codeBlock": {
    "code": "function add(a, b) {\n  return a + b;\n}",
    "lang": "ts",
    "file": "src/math.ts",
    "lines": "10-12",
    "highlights": [2]
  },
  "options": ["Approve", "Request changes"]
}

Options with code blocks:

{
  "options": [
    {
      "label": "Use async/await",
      "code": { "code": "const data = await fetch(url);", "lang": "ts" }
    },
    {
      "label": "Use promises",
      "code": { "code": "fetch(url).then(data => ...);", "lang": "ts" }
    },
    "Keep current implementation"
  ]
}

Diff display (set lang: "diff"):

{
  "codeBlock": {
    "code": "--- a/file.ts\n+++ b/file.ts\n@@ -1,3 +1,4 @@\n const x = 1;\n+const y = 2;\n const z = 3;",
    "lang": "diff",
    "file": "src/file.ts"
  }
}

CodeBlock Field	Type	Description
code	string	The code content (required)
lang	string	Language for display (e.g., "ts", "diff")
file	string	File path to display in header
lines	string	Line range to display (e.g., "10-25")
highlights	number[]	Line numbers to highlight
title	string	Optional title above code

Line numbers are shown when file or lines is specified. Diff syntax (+/- lines) is automatically styled when lang is "diff".

Keyboard Shortcuts

Key	Action
↑ ↓	Navigate options
← →	Navigate between questions
Tab	Cycle through options
Enter / Space	Select option
⌘+V	Paste image or file path
⌘+Enter	Submit form
Esc	Show exit overlay (press twice to quit)
⌘+Shift+L	Toggle theme (if enabled; appears in shortcuts bar)

Configuration

Settings in ~/.pi/agent/settings.json:

{
  "interview": {
    "timeout": 600,
    "port": 19847,
    "snapshotDir": "~/.pi/interview-snapshots/",
    "autoSaveOnSubmit": true,
    "theme": {
      "mode": "auto",
      "name": "default",
      "lightPath": "/path/to/light.css",
      "darkPath": "/path/to/dark.css",
      "toggleHotkey": "mod+shift+l"
    }
  }
}

Timeout precedence: params > settings > default (600s)

Snapshot settings:

• snapshotDir: Directory for saved interview snapshots (default: ~/.pi/interview-snapshots/)
• autoSaveOnSubmit: Automatically save snapshot on successful submit (default: true)

Port setting: Set a fixed port (e.g., 19847) to use a consistent port across sessions.

Theme notes:

• mode: dark (default), light, or auto (follows OS unless overridden)
• name: built-in themes are default and tufte
• lightPath / darkPath: optional CSS file paths (absolute or relative to cwd)
• toggleHotkey: optional; when set, toggles light/dark and persists per browser profile

Theming

The interview form supports light/dark themes with automatic OS detection and user override.

Built-in Themes

Theme	Description
default	Monospace, IDE-inspired aesthetic
tufte	Serif fonts (Cormorant Garamond), book-like feel

Theme Modes

• dark (default): Dark background, light text
• light: Light background, dark text
• auto: Follows OS preference, user can toggle and override persists in localStorage

Custom Themes

Create custom CSS files that override the default variables:

:root {
  --bg-body: #f8f8f8;
  --bg-card: #ffffff;
  --bg-elevated: #f0f0f0;
  --bg-selected: #d0d0e0;
  --bg-hover: #e8e8e8;
  --fg: #1a1a1a;
  --fg-muted: #6c6c6c;
  --fg-dim: #8a8a8a;
  --accent: #5f8787;
  --accent-hover: #4a7272;
  --accent-muted: rgba(95, 135, 135, 0.15);
  --border: #5f87af;
  --border-muted: #b0b0b0;
  --border-focus: #8a8a9a;
  --border-active: #9090a0;
  --success: #87af87;
  --warning: #d7af5f;
  --error: #af5f5f;
  --focus-ring: rgba(95, 135, 175, 0.2);
}

Then reference in settings or params:

{
  "interview": {
    "theme": {
      "mode": "auto",
      "lightPath": "~/my-themes/light.css",
      "darkPath": "~/my-themes/dark.css",
      "toggleHotkey": "mod+shift+l"
    }
  }
}

Toggle Hotkey

When toggleHotkey is set (e.g., "mod+shift+l"), users can switch between light/dark modes. The preference persists in the browser's localStorage across sessions.

Response Format

interface Response {
  id: string;
  value: string | string[];
  attachments?: string[];  // image paths attached to non-image questions
}

Example:

- framework: React [attachments: /path/to/diagram.png]
- features: Auth, Database
- notes: Need SSO support
- mockup: /tmp/uploaded-image.png

File Structure

interview/
├── index.ts       # Tool entry point, parameter schema
├── settings.ts    # Shared settings module
├── server.ts      # HTTP server, request handling
├── schema.ts      # TypeScript interfaces for questions/responses
└── form/
    ├── index.html # Form template
    ├── styles.css # Base styles (dark tokens)
    ├── themes/    # Theme overrides (light/dark)
    └── script.js  # Form logic, keyboard nav, image handling

Session Recovery

If an interview times out or is abandoned (tab closed, lost connection), the questions are automatically saved to ~/.pi/interview-recovery/ for later retry.

Recovery files:

• Location: ~/.pi/interview-recovery/
• Format: {date}_{time}_{project}_{branch}_{sessionId}.json
• Example: 2026-01-02_093000_myproject_main_65bec3f4.json
• Auto-cleanup: Files older than 7 days are deleted

To retry an abandoned interview:

interview({ questions: "~/.pi/interview-recovery/2026-01-02_093000_myproject_main_65bec3f4.json" })

Saving Interviews

Save a snapshot of your interview at any time for later review or to resume.

Manual Save:

• Click the Save button (header or footer)
• Saves to ~/.pi/interview-snapshots/ by default
• Creates folder with index.html + images/ subfolder

Auto-save on Submit:

• Enabled by default (autoSaveOnSubmit: true in settings)
• Automatically saves after successful submission
• Folder name includes -submitted suffix

Reviving a Saved Interview:

interview({ questions: "~/.pi/interview-snapshots/project-setup-myapp-main-2026-01-20-141523/index.html" })

The form opens with answers pre-populated. Edit and submit as normal.

Configuration:

{
  "interview": {
    "snapshotDir": "~/.pi/interview-snapshots/",
    "autoSaveOnSubmit": true
  }
}

Snapshot Structure:

~/.pi/interview-snapshots/
  {title}-{project}-{branch}-{timestamp}[-submitted]/
    index.html          # Human-readable + embedded JSON for revival
    images/
      mockup.png        # Uploaded images (relative paths in HTML)

Limits

• Max 12 images total per submission
• Max 5MB per image
• Max 4096x4096 pixels per image
• Allowed types: PNG, JPG, GIF, WebP