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.

Ask. Keep working. Get the answer.

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

With background: true, questions appear above your normal input without taking focus. The agent continues independent work. In fullscreen mode, click anywhere in the question panel to use its keyboard controls. Click a choice to answer or toggle it; click tabs and Review to navigate. Review actions need two clicks by default. Click your normal input to return to writing. Alt+Q also switches between answering and writing a message. Your answer arrives between turns, or wakes an idle agent.

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. New questions do not reopen a panel you've hidden. Press D on a question to skip just that question, not the whole form. In text editors, D is ordinary text.

If there's nothing else the agent can do, it calls wait_for_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 its first model request asks for confirmation because changing tools can invalidate the prompt cache. See question modes.

Pending background questions alone do not mark a responsive agent as blocked in Herdr. Foreground questions and active wait_for_answers calls do. Cancelling a background form cancels that question, not the agent.

It still has to wait before doing work that depends on your answer. “Keep working” doesn't mean “guess anyway.”

The bundled skill guides the agent to ask when a decision matters. It doesn't force every agent to behave.

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 and clarification requests. 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

The agent can look up earlier questions and answers, then export them as a Markdown artifact for your task:

• 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, durable history/export, external UI support, and Herdr status. It drops chat question extraction and manual answer/replay commands. The agent asks directly; the form needs no extra model call.

Herdr support includes maudelv's work; the skill was inspired by edlsh/pi-ask-user.

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