pi-ask/README.md

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

![pi-ask demo](docs/media/pi-ask-demo.gif)

[Link to high-quality video](https://github.com/user-attachments/assets/a8503ca9-afcb-4c31-9edc-353b985a0209)


## Install

```bash
pi install npm:@eko24ive/pi-ask
```

You can also install from git:

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

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

```bash
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

### Multi-question flow (tabs)
Move across several related questions in one ask flow.

![Multi-question ask_user flow with tab navigation](docs/media/feature-multi-question-tabs.png)

### Single-select question
Pick one option when answers are mutually exclusive.

![Single-select question with one selected option](docs/media/feature-single-select.png)

### Multi-select question
Choose multiple options when several answers apply.

![Multi-select question with multiple selected options](docs/media/feature-multi-select.png)

### Preview mode
Use a dedicated preview pane when options need richer detail.

![Preview question showing a dedicated preview pane](docs/media/feature-preview-pane.png)

### Custom answer (`Type your own`)
Capture free-form input inline without leaving the flow.

![Inline custom answer input for Type your own option](docs/media/feature-custom-answer-input.png)

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

![Native pi-style @ file references inside the ask flow](docs/media/feature-at-file-mentions.png)

### Option notes
Attach clarification notes to a specific option (`n`).

![Option note editor with note text for selected option](docs/media/feature-option-note.png)

### Question notes
Add notes at question level for broader context (`Shift+N`).

![Question-level note editor with saved note](docs/media/feature-question-note.png)

### Review tab — Submit
Review all answers before returning them to the agent.

![Review tab with Submit action highlighted](docs/media/feature-review-submit.png)

### Review tab — Elaborate
Ask the agent to elaborate on notes before finalizing choices.

![Review tab with Elaborate action and expanded note preview](docs/media/feature-review-elaborate.png)

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

```json
{
  "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](https://github.com/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`](docs/contract.md).

## Local development

### Run locally in pi

```bash
pi -e ./src/index.ts
```

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

```bash
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

```bash
pnpm install
```

### Install git hooks (contributors)

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

```bash
pnpm exec lefthook install
```

### Development commands

```bash
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`:

```bash
pnpm exec lefthook install
```

Recommended flow:

```bash
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