@geoqiao/pi-ask

[!IMPORTANT] This is an independently maintained continuation of eko24ive/pi-ask, with portable Pi RPC mode support while preserving the rich TUI experience.

@geoqiao/pi-ask is an ask tool that cares about your answers.

It lets an agent pause, ask structured questions in a terminal UI or portable Pi RPC dialogs, and continue with normalized answers instead of guessing.

High-quality video: demo.mp4

Upstream and contributions

This project preserves the upstream Git history, MIT license, and author attribution. New development and releases are maintained independently in the geoqiao/pi-tools monorepo. Issues and contributions are welcome there.

Install

pi install npm:@geoqiao/pi-ask

Or try it without installing (load once for the current run):

pi -e npm:@geoqiao/pi-ask

Features

Once installed, this package gives the agent a native way to ask for clarification instead of guessing. The rich interface is used in TUI mode.

• 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
• ⭐ Optional warning-colored (recommended) markers that do not preselect answers
• ✍️ Inline free-form Type your own answers
• 📎 Native pi-style @ file references inside answer and note editors
• 📝 Question-level and option-level notes
• 👀 Review tab with Submit, Elaborate, and Cancel
• 💬 Elaboration flow to capture note-based clarification before final submission
• 🔌 Pi RPC fallback using portable sequential dialogs with normalized results
• ⌨️ Context-aware customizable keymaps with aliases for main flow, editors, and settings
• ⚙️ Ask settings with persisted behaviour, notifications, keymaps, and /answer extraction config
• 🔔 Optional external notifications when an ask flow is waiting for input
• 🔁 Slash commands for fallback/replay:
  • /answer extracts questions from the latest assistant message into an ask flow
  • /answer:again reopens the latest /answer form on the current branch
  • /ask:replay replays the latest real ask_user form on the current branch
• 🛟 Automatic recovery of an unanswered ask_user form after startup, resume, or fork
• 🗣️ You can talk to your agent to configure pi-ask; it will read the bundled configuration guide and tailor the config for you

Feature walkthrough

Native @ file references

Use pi-style @ file path autocomplete inside free-form answers and note editors.

Option and question notes

Attach clarification notes to a specific option (n) or add broader question-level context (Shift+N).

Option notes	Question notes

Review tab — Elaborate and Submit

Ask the agent to elaborate on notes before finalizing choices, or review all answers before returning them to the agent.

Elaborate	Submit

Single-select and multi-select questions

Pick one option when answers are mutually exclusive, or choose multiple options when several answers apply.

Single-select	Multi-select

Preview mode

Use a dedicated preview pane when options need richer detail.

Custom answer (Type your own)

Capture free-form input inline without leaving the flow.

Default key bindings

Open ask settings with ? during the ask flow, or with the /ask-settings command from pi.

Keymaps are context-aware and configurable in ~/.pi/agent/extensions/eko24ive-pi-ask.json. The established filename is retained so users can switch from the upstream package without losing settings. Each action accepts a key string or an array of aliases.

Default contexts:

• global: dismiss (Ctrl+C) and settings (?)
• main: confirm/cancel/toggle, tab navigation, option navigation, and note shortcuts
• editor: custom answer submit/close and empty-editor navigation
• noteEditor: note save/close and empty-editor navigation
• settingsModal: close, next/previous setting, and toggle

Fixed bindings:

Key	Context	Effect
1..9	Options list	Select or toggle matching option
1 2 3	Review tab	Trigger Submit / Elaborate / Cancel
@	Editors	File-reference affordance
Arrow keys / Tab	Non-empty editor	Stay in editor for cursor movement

Review-tab shortcuts can optionally require the same number key twice via behaviour.doublePressReviewShortcuts. behaviour.presentSingleAsMulti can render future single-select questions as multi-select while preserving the requested type in results; use main.changeQuestionType (t by default) to change the active question type live.

You can edit the config file yourself, ask pi to edit it for you, or use /ask-settings to find the exact config path, toggle behaviour/notification settings, or reset config to defaults with a guarded double press. pi-ask treats the config file as user-owned: load-time migrations and invalid files are handled in memory without rewriting or backing up the file, and read-only/externally managed configs fail gracefully with a manual-edit message.

{
  "schemaVersion": 5,
  "answer": {
    "extractionModels": [
      { "provider": "openai-codex", "id": "gpt-5.4-mini" },
      { "provider": "github-copilot", "id": "gpt-5.4-mini" },
      { "provider": "anthropic", "id": "claude-haiku-4-5" }
    ],
    "extractionTimeoutMs": 30000,
    "extractionRetries": 1
  },
  "behaviour": {
    "autoSubmitWhenAnsweredWithoutNotes": false,
    "confirmDismissWhenDirty": true,
    "doublePressReviewShortcuts": true,
    "presentSingleAsMulti": false,
    "showFooterHints": true
  },
  "keymaps": {
    "global": { "dismiss": ["ctrl+c"], "settings": ["?"] },
    "main": {
      "confirm": ["enter"],
      "cancel": ["esc"],
      "toggle": ["space"],
      "changeQuestionType": ["t"],
      "nextTab": ["tab", "right"],
      "previousTab": ["shift+tab", "left"],
      "nextOption": ["down"],
      "previousOption": ["up"],
      "optionNote": ["n"],
      "questionNote": ["shift+n"]
    },
    "editor": {
      "submit": ["enter"],
      "close": ["esc"],
      "nextTabWhenEmpty": ["tab", "right"],
      "previousTabWhenEmpty": ["shift+tab", "left"],
      "nextOptionWhenEmpty": ["down"],
      "previousOptionWhenEmpty": ["up"]
    },
    "noteEditor": {
      "save": ["enter"],
      "close": ["esc"],
      "nextTabWhenEmpty": ["tab", "right"],
      "previousTabWhenEmpty": ["shift+tab", "left"],
      "nextOptionWhenEmpty": ["down"],
      "previousOptionWhenEmpty": ["up"]
    },
    "settingsModal": {
      "close": ["esc", "ctrl+c", "?"],
      "nextOption": ["down"],
      "previousOption": ["up"],
      "toggle": ["enter", "space"]
    }
  },
  "notifications": {
    "enabled": true,
    "channels": ["bell"]
  }
}

Accepted notation follows pi-tui key ids. Common aliases are normalized, for example escape → esc, return → enter, control+c → ctrl+c, and Shift+N → shift+n.

Use

After installation, the extension registers the ask_user tool plus /ask-settings, /answer, /answer:again, and /ask:replay commands.

Agents first read available context and call ask_user only for unresolved critical requirements, outcome-changing preferences, or consequential/hard-to-reverse actions beyond existing authorization. Explicitly requested interviews and requirements gathering also use the tool.

Clear small changes, settled choices, authorized reversible steps, and routine implementation details proceed without reconfirmation. Multiple options or an architecture/naming/research label alone do not trigger questions; clear comparison/research requests get analysis first. Questions stay on current blockers, and settled decisions reopen only for materially new information. Delegated autonomy does not waive safety boundaries, and cancellation or missing/unclear answers never supplies high-risk approval. This is prompt guidance, not a runtime permission check; see the policy and verification limits and skill examples.

Agents can mark any number of grounded preferences with recommended: true and use option descriptions for reasons. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style @ file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from ? in the ask flow and from the /ask-settings command. Behaviour and notification settings are binary on/off toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.

Pi RPC fallback

When Pi runs in RPC mode with portable extension UI support, ask_user keeps the same normalized result contract but uses sequential dialogs:

• each question card contains only its real options plus Type something…
• selecting a real option and submitting advances directly to the next question or completes the flow
• Type something… opens one input dialog; on multi questions it is the fallback for entering multiple choices
• dismissing a question or its input skips that question instead of cancelling the flow
• recommendation markers, descriptions, and preview content are flattened into readable option strings without changing canonical values or labels
• multiple questions include [current/total] progress in each dialog title
• tool abort signals close portable select/input dialogs and return cancelled: true

RPC intentionally does not reproduce the tabbed same-screen form, native checkbox cards, repeated multi-select cards, notes, Skip/Cancel option rows, custom preview pane, question-type hotkeys, settings overlay, or final Submit/Elaborate review tab. The fallback completes in submit mode after the sequential questions. /answer, /answer:again, /ask:replay, and /ask-settings remain TUI-only.

Answer and replay commands

/answer is useful when the agent asked questions in plain text instead of using ask_user. It supplies the preceding user message as context, asks the configured extraction model for one synthetic ask_user tool call, validates the result, and opens the same ask UI. Missing or invalid tool calls are retried; raw and fenced JSON text remain supported as fallbacks.

Replay commands are branch-aware. They read persisted entries from the current pi session branch, so they work naturally with /resume, /tree, and conversation branching:

• /answer:again reopens the latest form created by /answer on this branch
• /ask:replay reopens the latest real ask_user form on this branch

Cancellation is local to the UI: closing a replayed form does not start a new agent turn. Submitted answers are sent back as a normal user follow-up message.

Interrupted ask forms

If Pi stops while an ask_user form is open, the tool call remains without a result. Starting, resuming, or forking that session reopens the newest unanswered form once. Submitting sends the result as a user message because the original tool execution no longer exists. Cancelling dismisses the automatic recovery. Either outcome prevents another automatic reopen, while /ask:replay remains available.

New sessions, extension reloads, non-TUI modes, and RPC sessions do not trigger recovery.

Kudos to @k0valik for the /answer idea.

You can also talk to pi to configure this extension. When asked to customize pi-ask settings, keymaps, notifications, or extraction behavior, the agent is instructed to read the bundled docs/configuration.md guide first and then edit the config file accordingly.

This package also bundles the ask-user skill profile from skills/ask-user/SKILL.md. It reinforces when to use the tool, is enabled by default when installed, and can be disabled via pi config. The skill was inspired by https://github.com/edlsh/pi-ask-user.

You can still add your own agent instruction if you want to further reinforce usage.

For exact input/output and UX guarantees, see docs/contract.md.

Local development

Run locally in pi

pi -e ./src/index.ts

Run in isolated test mode (extension + bundled skill only)

pnpm dev
pnpm dev ../test

pnpm dev [path] runs pi with --no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files, loads this repo’s extension and skills/ask-user, and starts pi from [path] by changing directories before launch (defaults to .).

Install dependencies

pnpm install

Install git hooks (contributors)

lefthook is not installed automatically. If you want the local commit hooks used by this repo, run:

pnpm exec lefthook install

Development commands

pnpm format
pnpm lint
pnpm check
pnpm typecheck
pnpm test

Commit workflow

This monorepo uses lefthook, Commitizen, conventional commitlint, and Changesets.

If you want local hooks, install them once after pnpm install:

pnpm exec lefthook install

From the repository root, the recommended flow is:

pnpm commit

User-facing changes should also include a Changeset created with pnpm changeset.

Project layout

• src/ — TypeScript extension implementation
• tests/ — behavior-focused tests
• docs/ — small docs set for contract and architecture
• docs/media/ — repository-only README media assets

Documentation

Docs stay intentionally small:

• docs/README.md — index
• docs/contract.md — external behavior
• docs/architecture.md — module boundaries and invariants