# Ask User Questions Mcp

> Better 'AskUserQuestion' - A lightweight MCP server/OpenCode plugin/Agent Skills + CLI interface which allows parallel AI agents ask questions to you. Be the human in the human-in-the-loop!

- **Type:** MCP server
- **Install:** `agentstack add mcp-paulp-o-ask-user-questions-mcp`
- **Verified:** Pending review
- **Seller:** [paulp-o](https://agentstack.voostack.com/s/paulp-o)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [paulp-o](https://github.com/paulp-o)
- **Source:** https://github.com/paulp-o/ask-user-questions-mcp

## Install

```sh
agentstack add mcp-paulp-o-ask-user-questions-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AUQ - Ask User Questions

_`AskUserQuestion` pushed to the max_

[](https://www.npmjs.com/package/auq-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://cursor.com/en-US/install-mcp?name=ask-user-questions&config=eyJlbnYiOnt9LCJjb21tYW5kIjoibnB4IC15IGF1cS1tY3Atc2VydmVyIHNlcnZlciJ9)

**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](#-install-cli-tool) • [Usage](#-usage)

> 🤔 [I already have question tool in CC/OC/Cursor. Why use this?](#-why-auq-vs-built-in-questioning-tools)

---

## 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**!

A no no fun background story

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

---

# Setup Instructions

## 🚀 Install CLI Tool

First, install the **AUQ CLI**:

### Global Installation (Recommended)

**Bun (recommended — required for default OpenTUI renderer)**

```bash
bun add -g auq-mcp-server
```

**npm**
```bash
npm install -g auq-mcp-server
```

**pnpm**
```bash
pnpm add -g auq-mcp-server
```

**yarn**
```bash
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.

Local (Project-specific) Installation

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

Sessions are stored **globally** regardless of installation method. See [Troubleshooting](#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](#option-c-agent-skills-experimental). Use [OpenCode plugin](#option-b-opencode-plugin) if you use OpenCode._

Cursor

[](https://cursor.com/en-US/install-mcp?name=ask-user-questions&config=eyJlbnYiOnt9LCJjb21tYW5kIjoibnB4IC15IGF1cS1tY3Atc2VydmVyIHNlcnZlciJ9)

Claude Code

**Method 1: Using CLI** (Recommended)

```bash
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):

```json
{
  "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.

Codex CLI

Add to `~/.codex/config.toml`:

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

Claude Desktop

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

```json
{
  "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`:

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

Limitations

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

```bash
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:

```markdown
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):

   ```bash
   AUQ_RENDERER=ink auq    # force ink
   AUQ_RENDERER=opentui auq  # force opentui
   ```

2. **Config file** (`.auqrc.json`):

   ```json
   {
     "renderer": "ink"
   }
   ```

3. **CLI command**:
   ```bash
   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 color themes                               |
| `[`/`]`  | Sessions      | Switch to previous/next session (OpenTUI: also click session dots) |

**Mouse Support (OpenTUI renderer only):**

| Action            | Description                                     |
| ----------------- | ----------------------------------------------- |
| Click option      | Select/toggle option                            |
| Scroll            | Scroll through session picker or update overlay |
| Click session dot | Switch to that session                          |

⌨️ All Keyboard Shortcuts

| Key      | Action                                                             |
| -------- | ------------------------------------------------------------------ |
| `↑↓`     | Navigate options                                                   |
| `←→/Tab` | Switch between questions                                           |
| `Space`  | Select/toggle option without advancing                             |
| `Enter`  | Select option and advance to next question                         |
| `R`      | Select recommended option(s) for current question                  |
| `Ctrl+R` | Quick submit — auto-fill recommended, go to review                 |
| `Esc`    | Reject the whole question set and optionally explain why            |
| `Ctrl+T` | Cycle through available color themes                               |
| `Ctrl+S` | Open session picker                                                |
| `1-9`    | Jump directly to session by number                                 |
| `[/]`    | Navigate between sessions                                          |
| `U`      | Open update overlay (when update available)                        |

More Commands (advanced)

```bash
# you won't likely need these at all
auq server       # Start MCP server
auq --version    # Show version
auq update       # Check for and install updates
auq --help       # Show help
```

---

📋 Full CLI Reference

### CLI Commands

AUQ provides headless CLI commands for managing sessions and configuration without the TUI.
Run `auq --help` for the complete reference.

#### Answer Sessions

```bash
auq answer  --answers '{"0": {"selectedOption": "option1"}}'
auq answer  --answers '{"0": {"selectedOptions": ["A", "B"]}}'  # multi-select
auq answer  --answers '{"0": {"customText": "free text"}}'  # custom text
auq answer  --reject --reason "Not applicable"
auq answer  --answers '...' --force  # abandoned session
auq answer  --answers '...' --json
```

#### Manage Sessions

```bash
auq sessions list                    # pending sessions (default)
auq sessions list --stale             # stale sessions only
auq sessions list --all               # all sessions
auq sessions show          # session details
auq sessions dismiss       # dismiss stale session
auq sessions dismiss  --force
auq sessions list --limit 10 --page 2 # pagination
auq sessions list --json
```

#### Session History

```bash
auq history                           # list session history
auq history --all                     # include abandoned
auq history --unread                  # unread only
auq history --search "deploy"          # search
auq history --limit 10 --page 2       # pagination
auq history show           # full Q&A detail
auq history --json
```

#### Fetch Answers (Programmatic)

```bash
auq fetch-answers --unread            # list unread answered sessions
auq fetch-answers          # fetch specific session
auq fetch-answers  --blocking  # wait until answered
auq fetch-answers --limit 10 --page 2
auq fetch-answers --json
```

#### Configuration

```bash
auq config get                        # view all
auq config get staleThreshold         # view specific
auq config set staleThreshold 3600000 # set local
auq config set staleThreshold 3600000 --global  # set global
```

#### Update

```bash
auq update        # interactive update check
auq update -y     # skip confirmation
```

#### Pagination

List commands (`sessions list`, `history`, `fetch-answers`) support:
- `--limit ` — Max items per page (default: 20)
- `--page ` — Page number (default: 1)

🌍 Environment Variables

| Variable             | Description                                      |
| -------------------- | ------------------------------------------------ |
| `AUQ_RENDERER`       | Override renderer (`"ink"` or `"opentui"`)          |
| `AUQ_SESSION_DIR`    | Custom session storage directory                 |
| `XDG_CONFIG_HOME`    | Custom config directory (default: `~/.config`)   |
| `NO_UPDATE_NOTIFIER` | Set to `"1"` to disable update checks             |

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

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

#### Disabling update checks

Disable automatic update checks via config:

```bash
auq config set updateCheck false
```

Or set the environment variable:

```bash
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

| Feature          | ink                | OpenTUI                                   |
| ---------------- | ------------------ | ----------------------------------------- |
|

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [paulp-o](https://github.com/paulp-o)
- **Source:** [paulp-o/ask-user-questions-mcp](https://github.com/paulp-o/ask-user-questions-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-paulp-o-ask-user-questions-mcp
- Seller: https://agentstack.voostack.com/s/paulp-o
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.