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!

---

✨ Demo

---

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.

---

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

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.

---

💻 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:

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

Mouse Support (OpenTUI renderer only):

---

Stale Session Detection

Sessions that remain unanswered longer than the configured threshold are marked as “stale” (potentially orphaned). This helps identify sessions where the AI may have disconnected or timed out.

• Visual indicators: Stale sessions show a ⚠ warning icon and yellow highlighting in the TUI
• Toast notifications: A notification appears when a session becomes stale (configurable)
• Grace period: Interacting with a stale session provides a 30-minute grace period
• Configurable threshold: Default is 2 hours (7,200,000ms)

---

Abandoned Session Handling

When an AI client disconnects, associated sessions are marked as “abandoned”. These sessions:

• Remain visible in the TUI with a red indicator
• Show a confirmation dialog before answering (“AI가 disconnect되었습니다”)
• Can still be answered via CLI with the --force flag
• Are detectable via auq sessions list --all

---

Auto-Update

AUQ automatically checks for updates and keeps itself up to date.

How it works

• All updates (patch, minor, major): A fullscreen overlay is shown with changelog and options to update, skip, or defer.
• Update checks: Run on every TUI launch (no delay/cache).
• CLI notification: When running non-TUI commands, a one-line update notification is shown if a newer version is available.

Manual update

Run auq update to manually check for and install updates:

auq update        # Interactive update check
auq update -y     # Skip confirmation prompt

Disabling update checks

Disable automatic update checks via config:

auq config set updateCheck false

Or set the environment variable:

NO_UPDATE_NOTIFIER=1 auq ask "question"

Update checks are automatically disabled in CI environments (CI=true).

The auq update command always works regardless of these settings.

Theme System

AUQ supports 16 built-in color themes with automatic persistence. Press Ctrl+T to cycle through themes.

Theme Differences by Renderer

Both renderers support all 16 built-in themes and custom themes. Colors are consistent; only implementation details differ.

Your selected theme is automatically saved to ~/.config/auq/config.json and restored on next launch.

---

Manual session cleanup

Sessions auto-clean after retention period. However, you can manually clean them up if you want to.

rm -rf ~/Library/Application\ Support/auq/sessions/*  # macOS
rm -rf ~/.local/share/auq/sessions/*                  # Linux

---

Language Support

AUQ supports multiple languages for the TUI interface:

• English (en) - Default
• Korean (ko) - 한국어

Language is auto-detected from system locale (LANG, LC_ALL, LC_MESSAGES environment variables) when set to "auto".

Desktop Notifications

AUQ uses native desktop notifications to alert you when new questions arrive.

Platform Requirements

Notifications can be disabled in configuration if needed.

Features:

• Batched Notifications: Rapid session arrivals are batched into a single notification
• Progress Bar: Shows question completion progress in terminal dock icon (supported terminals like iTerm2 and WezTerm)
• Native Integration: Uses system-native notification centers

Configuration:

{
  "notifications": {
    "enabled": true,
    "sound": true
  }
}

• notifications.enabled (default: true): Enable desktop notifications
• notifications.sound (default: true): Play sound with notifications

Set notifications.enabled to false to disable all notifications.

---

🤔 Why AUQ vs. Built-in Questioning Tools?

A clean decision inbox so you & AI stay in flow.

You’re an AI power user, running multiple agents on multiple instances. Highly parallelized, the AIs ask questions to you simultaneously, on multiple threads—scattered across different windows. AUQ enables them to ask anytime, collects everything in one inbox, and lets you respond on your terms—then elegantly routes answers back to each agent.

       Claude Code    Cursor    OpenCode
            │           │           │
            ▼           ▼           ▼
          ┌─────────────────────────────┐
          │        📥 AUQ Inbox         │
          └─────────────────────────────┘
                        │
                        ▼
                      🖥️ TUI
                        │
                        ▼
          ┌─────────────────────────────┐
          │       Your Answers          │
          └─────────────────────────────┘
            │           │           │
            ▼           ▼           ▼
       Claude Code    Cursor    OpenCode

📥 One Inbox for All Agents — Multiple agents ask in one place. One queue, one source of truth.

🧠 Teach the AI — Reject bad questions and tell it why. Turn “no” into better follow-ups.

❓ Fix the Question First — Can’t answer because it’s vague? Request elaboration before you guess.

⚡ Blast Through the Obvious — Ctrl+R accepts all recommended options. Focus on the hard decisions.

🔔 Pinged When It Matters — Native notifications, batched so you’re not spammed.

🌐 Works Where You Work — SSH into a remote server? AUQ runs there too.

---

📄 License

MIT License - see LICENSE file for details.

---

[1] arXiv:2308.13507