@eko24ive/pi-ask

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

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

High-quality video: demo.mp4

Install

pi install npm:@eko24ive/pi-ask

You can also install from git:

pi install git:github.com/eko24ive/pi-ask

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

pi -e npm:@eko24ive/pi-ask

Features

Once installed, this package gives the agent a native way to ask for clarification instead of guessing.

• 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
• ✍️ 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
• ⌨️ Fast keyboard-first interaction with customizable ask keymaps (also mobile-friendly in remote sessions)
• ⚙️ Ask settings with persisted behaviour, keymap customization, and /answer extraction config
• 🔁 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
• 🗣️ 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.

Customizable via config:

Action	Default key
Cancel flow or close/save editor draft	Esc
Dismiss entire ask flow immediately	Ctrl+C
Toggle selected option	Space
Confirm / continue / save / submit	Enter
Edit selected option note	n
Edit question note	Shift+N

Fixed bindings:

Key	Context	Effect
?	Ask flow / empty editor	Open ask settings
Tab Shift+Tab	Main flow	Switch tabs
← →	Main flow	Switch tabs
↑ ↓	Main flow	Move cursor
1..9	Options list	Select or toggle matching option
1 2 3	Review tab	Trigger Submit / Elaborate / Cancel
↑ ↓	Review tab	Change highlighted review action
↑ ↓	Empty editor	Move options without closing editor
Tab Shift+Tab / ← →	Empty editor	Switch tabs without closing editor
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.

Config file: ~/.pi/agent/extensions/eko24ive-pi-ask.json

You can edit this file yourself, ask pi to edit it for you, or use /ask-settings to find the exact config path and toggle behaviour settings.

{
  "schemaVersion": 2,
  "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,
    "showFooterHints": true
  },
  "keymaps": {
    "cancel": "esc",
    "dismiss": "ctrl+c",
    "toggle": "space",
    "confirm": "enter",
    "optionNote": "n",
    "questionNote": "shift+n"
  }
}

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 can auto-discover and call ask_user when they need clarification instead of guessing. 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 settings are binary on/off toggles that save immediately; customizable ask keymaps are changed by editing the shown config file path.

Answer and replay commands

/answer is useful when the agent asked questions in plain text instead of using ask_user. It extracts questions from the latest completed assistant message and opens the same ask UI.

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.

Kudos to @k0valik for the /answer idea.

You can also talk to pi to configure this extension. When asked to customize pi-ask settings or keymaps, 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 repo uses lefthook, Commitizen, conventional commitlint, and semantic-release.

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

pnpm exec lefthook install

Recommended flow:

pnpm commit

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