pi-agent-ask

You gave your agent an obscure task. It didn't understand a damn thing.

Instead of blindly following your bullshit, it asks a question.

And it keeps working while you answer.

Install

Install Pi, then:

pi install npm:pi-agent-ask

Or install directly from GitHub:

pi install git:github.com/alexshpunt/pi-agent-ask

Remove any other pi-ask installation so only one extension provides ask_user, then reload Pi.

Why this one

• The agent asks in the background and keeps working. You answer when you get to it.
• The question panel isn't modal. It sits above your input, your message draft stays, and Esc puts the questions aside for later.
• Answers arrive as you give them: between turns, or by waking an idle agent. When the agent has nothing else to do, it can call wait_for_answers. In Background-only mode it never waits at all.
• It's lean on context: two short tool descriptions, a small schema and compact answers. The whole ask_user declaration is about 2,000 characters. The package adds no system-prompt rules or bundled skill, so when and how often to ask stays with your own instructions.
• You answer with more than a click: pick options, write your own answer, leave notes on any option, paste screenshots.
• A question can carry its context, as text or as the absolute path of a file. The form shows it beside the options, so you don't have to dig through the chat.

Ask. Keep working. Get the answer.

The agent calls ask_user. You get a form with choices, the context you need to answer, your own answer, and notes. Not another wall of text to untangle.

With background: true, the form appears above your normal input and takes keyboard focus. Alt+Q or a click switches between answering and writing a message. Your answer arrives between turns, or wakes an idle agent. Forms queue one at a time, in order.

Press Esc in the question panel or run /ask-defer to put all questions aside. The queue and drafts stay saved; /ask-queue reopens them. Press D on a question to skip just that question. Cancelling a background form cancels that question, not the agent.

The agent can call wait_for_answers to wait for your answers. Hiding the panel or sending a normal message releases that wait without cancelling the questions.

Want the agent to stay available instead of waiting? Run /ask-mode and opt into Background-only, globally or for a trusted project. Every question then uses the queue, and the agent has no wait tool. Changing the mode after the first model request asks for confirmation because changing tools can invalidate the prompt cache. See question modes.

An open question panel marks the session as blocked in Herdr, so pending questions are visible outside the terminal. Hiding the panel clears that mark while keeping the queue.

Paste a screenshot into your answer

In Type your own, a question note, or an option note, use Pi's image-paste shortcut shown in the form. It is usually Ctrl+V on Linux/macOS and Alt+V on Windows/WSL. Paste several images if needed; Ctrl+Alt+D removes the last image in that editor.

The form shows [1 image], not a graphical preview. Text is optional. The agent receives the image itself, including in background answers. Images stay in session history; Markdown exports embed them as data URIs, which not every viewer can display.

Linux needs a working native clipboard, wl-paste, or xclip. WSL can read screenshots from the Windows clipboard through PowerShell. File-path attachments and remote-client image uploads are not included.

Your answers aren't disposable

Questions and answers are recorded automatically. To let the agent look them up and export them as Markdown, enable the opt-in history tools:

• list_ask_history finds past questions.
• read_ask_history reads the question, choices, answer, and notes.
• export_ask_history exports all or selected records.

The journal survives compaction, reload, and resume. It follows the current session branch, not every conversation you've ever had. Unfinished forms can recover too.

The boring bits

Use /ask-settings, or press ? in a form. See configuration, tool behavior, and integration events.

This fork of eko24ive/pi-ask adds background questions, waiting, question context, durable history/export, external UI support, and Herdr status. It drops chat question extraction, manual answer/replay commands, and the Elaborate action. The agent asks directly; the form needs no extra model call.

Herdr support includes maudelv's work.

Found a weird case? Open an issue. Got an idea? Start a discussion. Contributions welcome. MIT.