AUQ - Ask User Questions

AskUserQuestion pushed to the max

A complete toolset that enables maximum level of human-(intention-)in-the-loop onto any long-running, multi-agentic AI workflows (like Ralph Loop!).

Single/multiple choice questions, custom options, multi-agent interoperability, question queueing, question rejection with explanation, elaboration requesting, quick recommendations auto-selection, themes, native OS notification, terminal progress bar, multi-language support, agent skills support... and more. You can customize them all too!

Can be used via MCP server / OpenCode plugin / Agent Skills.

Setup • Usage

🤔 I already have question tool in CC/OC/Cursor. Why use this?

What does it do?

AUQ lets your AI assistants ask clarifying questions consisting of multiple-choice/single-choice questions (with an "Other" option for custom input / rejection / ask for elaboration) while coding or working, and wait for your answers through a separate CLI window without messing up your workflow.

This lets you inject your intent into long-running autonomous AI tasks—no more switching windows or babysitting AIs. Turn on the CLI anytime, even remotely via SSH!

In AI-assisted coding, guiding LLMs to ask clarifying questions have been widely recognized as a powerful prompt engineering technique to overcome LLM hallucination and generate more contextually appropriate code [1].

On October 18th, Claude Code 2.0.21 introduced an internal AskUserQuestion tool. Inspired by it, I decided to build a similar tool that is:

• Integration-flexible - Works with MCP clients (Claude Desktop, Cursor, etc.) and has official OpenCode plugin support
• Non-invasive - Doesn't heavily integrate with your coding CLI workflow or occupy UI space
• Multi-agent friendly - Supports receiving questions from multiple agents simultaneously in parallel workflows

✨ Demo

https://github.com/user-attachments/assets/3a135a13-fcb1-4795-9a6b-f426fa079674

Setup Instructions

🚀 Install CLI Tool

First, install the AUQ CLI:

Global Installation (Recommended)

Bun (recommended — required for default OpenTUI renderer)

bun add -g auq-mcp-server

npm

npm install -g auq-mcp-server

pnpm

pnpm add -g auq-mcp-server

yarn

yarn global add auq-mcp-server

Note: Bun is recommended for the default OpenTUI renderer. When installed via npm/pnpm/yarn, the shell wrapper auto-detects Bun at runtime. If Bun is not available, it falls back to Node.js with the legacy Ink renderer.

# Install in your project
bun add auq-mcp-server

Sessions are stored globally regardless of installation method. See Troubleshooting for session locations.

🔌 Integrate to your AI

AUQ supports multiple AI environments. Choose between OpenCode plugin and MCP server.

Option A: MCP Server

Note: Due to differences in how some MCP clients are implemented, AUQ may be forcibly cancelled in tools that do not allow extending the global MCP timeout. If that's the case, consider using Agent Skills. Use OpenCode plugin if you use OpenCode.

Method 1: Using CLI (Recommended)

claude mcp add --transport stdio ask-user-questions -- bunx -y auq-mcp-server server

Note: npx also works if you prefer npm.

Method 2: Manual Configuration

Add to .mcp.json in your project root (for team-wide sharing):

{
  "mcpServers": {
    "ask-user-questions": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "auq-mcp-server", "server"]
    }
  }
}

Or add to ~/.claude.json for global access across all projects.

Note: Replace bunx if you don't use bun.

Verify setup: Type /mcp in Claude Code to check server status.

Add to ~/.codex/config.toml:

[mcp_servers.ask-user-questions]
command = "bunx"
args = ["-y", "auq-mcp-server", "server"]
tool_timeout_sec = 99999  // Extend timeout for long sessions

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ask-user-questions": {
      "command": "bunx",
      "args": ["-y", "auq-mcp-server", "server"]
    }
  }
}

Replace bunx if you don't use bun.

Restart Claude Desktop after saving.

Option B: OpenCode Plugin

Direct integration for OpenCode users. Adds working directory viewability feature exclusively.

Configuration

Add to opencode.json:

{
  "plugin": ["@paulp-o/opencode-auq@latest"]
}

Option C: Agent Skills (Experimental)

Usage with Skills-Compatible Agents

Copy the skills/ask-user-questions/ folder to your agent's skills directory.

This skill guides the AI to use AUQ CLI's hidden command, auq ask with raw JSON as parameters. Unlike MCP or proper tool harness systems, malformed JSON healing/schema enforcement aren't supported natively; therefore a less capable model could struggle to call properly.

💻 Usage

Starting the CLI tool

auq       # if installed globally (bun add -g)
# bunx auq
# npx auq

Start by defining your workflow to use AUQ tool for clarifying questions, on AGENTS.md (or CLAUDE.md), like:

Whenever you need clarification on what you are working on, never guess, and call AUQ(ask-user-questions).

When the AI asks questions, you'll see them appear in the AUQ TUI. Answer them at your convenience.

Renderer Selection

AUQ supports two terminal rendering engines:

| Renderer | Description | Status | | --------------------- | --------------------------------------------------- | ------------------- | | OpenTUI (default) | Native Zig-based renderer with improved performance | Stable (requires Bun) | | ink | React-based terminal renderer | Fallback (Node.js) |

OpenTUI is the default renderer and requires Bun runtime. When Bun is unavailable, AUQ automatically falls back to the Ink renderer.

To force a specific renderer, set one of the following (in priority order):

1. Environment variable (highest priority):

   AUQ_RENDERER=ink auq    # force ink
   AUQ_RENDERER=opentui auq  # force opentui
   

2. Config file (.auqrc.json):

   {
     "renderer": "ink"
   }
   

3. CLI command:

   auq config set renderer ink
   

Note: OpenTUI provides native CJK character support, built-in markdown rendering with syntax highlighting, and mouse support. The shell wrapper (bin/auq) auto-detects Bun at runtime.

Markdown rendering in question prompts

Question prompts now support Markdown formatting in the prompt text.

• Supported: bold, italic, ~~strikethrough~~, inline code, links, and fenced code blocks (with syntax highlighting)
• Links render as text (url) for broad terminal compatibility
• Code blocks use theme-aware colors (background/text/border)
• Always enabled (no configuration needed)
• Plain text prompts pass through unchanged
• Graceful fallback: if Markdown parsing fails, the raw text is shown

Note: AUQ is an unopinionated tool and doesn't include prompts on HOW AI should leverage it. It is expected that you do your own prompt engineering to make the most out of it in your own workflows. I personally enjoy prompting it to ask at least 30 questions repeatedly before action!

Recommended Setups

It is recommended to disable the built-in questioning tool in your harness (like the question tool in OpenCode or AskUserQuestion in Claude Code) to avoid AI from mixing them up.

Useful Keyboard Shortcuts

| Key | Action | Description | | -------- | ------------- | ------------------------------------------------------------------ | | Space | Select | Select/toggle option without advancing | | Enter | Select & Next | Select option and advance to next question | | R | Recommended | Select recommended option(s) for current question | | Ctrl+R | Quick Submit | Auto-select recommended options for all questions and go to review | | Esc | Reject | Reject the whole question set and optionally explain why to the AI | | Ctrl+T | Theme | Cycle through available colo