---
slug: "avtc-pi-ask-user-question"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/avtc/avtc-pi-ask-user-question@main/README.md"
repo: "https://github.com/avtc/avtc-pi-ask-user-question"
source_file: "README.md"
branch: "main"
---
# avtc-pi-ask-user-question

A question tool for the agent — single/multi-select or free-text, with subagent forwarding and attention alerts.

## Features

- **Single & multi-select** — pick one option or check several; each option has a label and description
- **Free-text "Other"** — every question has a row to type a custom answer
- **Multiline free-text** (`Ctrl`/`Shift`/`Cmd`+`Enter` = newline)
- **Multi-question tabs** — up to four questions in one dialog, each with a short header
- **Subagent forwarding** — questions from subagent [`avtc-pi-subagent`](https://github.com/avtc/avtc-pi-subagent) sessions are bridged [`avtc-pi-subagent-ui-bridge`](https://github.com/avtc/avtc-pi-subagent-ui-bridge) to the root UI as a single unified dialog
- **Attention alerts** — integrates with [`avtc-pi-notification`](https://github.com/avtc/avtc-pi-notification) to notify you when the agent is waiting
- **Dialog coordination** — uses [`avtc-pi-ui-components`](https://github.com/avtc/avtc-pi-ui-components) dialog coordinator to prevent overlapping dialogs across extensions.

## Tools

| Tool | Description |
|---|---|
| `ask_user_question` | Ask the user 1–4 structured questions (single-select, multi-select, or free-text) and wait for answers |

## What it looks like

**Single-select**

![Single select question](https://github.com/avtc/avtc-pi-ask-user-question/raw/HEAD/assets/images/single-select.png)

**Multi-select, multiple questions, and multiline free-text**

![Multi-select with checkboxes across tabbed questions, including a multiline free-text answer](https://github.com/avtc/avtc-pi-ask-user-question/raw/HEAD/assets/images/multi-select-multi-tab-multi-line.png)

**Submit review**

![Submit tab showing all answers](https://github.com/avtc/avtc-pi-ask-user-question/raw/HEAD/assets/images/submit.png)

## Installation

```bash
pi install npm:avtc-pi-ask-user-question
```

## Usage

Once installed, the tool is available to the agent automatically. Ask it to clarify something before proceeding — it calls `ask_user_question`, you answer in the TUI, and it continues with your answers:

```
Help me scaffold a new web app. Ask me what you need to know first.
```

## Key bindings

| Key | Action |
|---|---|
| `↑` `↓` | Move cursor |
| `Enter` | Select / confirm / submit |
| `Space` | Toggle (multi-select) |
| `Tab` | Open the free-text editor (on the "Other" row) |
| `←` `→` | Switch tabs |
| `Esc` | Cancel (or discard free-text) |

## Full suite

Check out the full suite of related extensions, [avtc-pi](https://github.com/avtc/avtc-pi) — deterministic feature development, subagent delegation, working-memory, behavioral learning, parallel-work guardrails, durable decisions, notifications, and more.

Developed with [Z.ai](https://z.ai/subscribe?ic=N5IV4LLOOV) — get 10% off your subscription via this referral link.

## Attribution

Inspired by Claude Code's `AskUserQuestion` tool.
Fork of [ghoseb/pi-askuserquestion](https://github.com/ghoseb/pi-askuserquestion).

## License

MIT