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

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

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

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.

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.

# 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

CLI Commands

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

Answer Sessions

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

Manage Sessions

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

Session History

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 <sessionId>          # full Q&A detail
auq history --json

Fetch Answers (Programmatic)

auq fetch-answers --unread            # list unread answered sessions
auq fetch-answers <sessionId>         # fetch specific session
auq fetch-answers <sessionId> --blocking  # wait until answered
auq fetch-answers --limit 10 --page 2
auq fetch-answers --json

Configuration

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

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

Pagination

List commands (sessions list, history, fetch-answers) support:

• --limit <N> — Max items per page (default: 20)
• --page <N> — Page number (default: 1)

Create custom themes by placing .theme.json files in:

• macOS/Linux: ~/.config/auq/themes/

Example custom theme (~/.config/auq/themes/my-theme.theme.json):

{
  "name": "my-theme",
  "colors": {
    "primary": "#ff6b6b",
    "success": "#51cf66",
    "text": "#f8f9fa"
  }
}

Custom themes inherit from the default dark theme—only override the colors you want to change. See the JSON schema for all available properties.

To test the MCP server and CLI locally during development:

1. Start the MCP Server (Terminal 1)

# Option A: Run with tsx (recommended for development)
bun run start

# Option B: Run with fastmcp dev mode (includes web inspector at http://localhost:6274)
bun run dev

# Option C: Run the built version
bun run build && bun run server

2. Create a Test Session (Terminal 2)

Use the auq ask command to create a session and wait for answers:

# Run directly with bun during development
bun run bin/auq.tsx ask '{"questions": [{"prompt": "Which language?", "title": "Lang", "options": [{"label": "TypeScript"}, {"label": "Python"}], "multiSelect": false}]}'

# Or pipe JSON to stdin
echo '{"questions": [{"prompt": "Which database?", "title": "DB", "options": [{"label": "PostgreSQL"}, {"label": "MongoDB"}], "multiSelect": false}]}' | bun run bin/auq.tsx ask

This will create a session and wait for the TUI to provide answers.

3. Answer with the TUI (Terminal 3)

# Run the TUI to answer pending questions
bun run bin/auq.tsx

Create Mock Sessions for TUI Testing

To test the TUI with multiple pending sessions:

# Create 3 mock sessions (default)
bun run scripts/create-mock-session.ts

# Create a specific number of sessions
bun run scripts/create-mock-session.ts 5

Then run the TUI to see and answer them:

bun run bin/auq.tsx

Verify MCP and CLI Use Same Session Directory

Both components should report the same session directory path. Check the logs:

• MCP server logs session directory on startup
• auq ask prints [AUQ] Session directory: <path> to stderr

On macOS, both should use: ~/Library/Application Support/auq/sessions

Development Commands

# Regenerate the skill from source
bun run generate:skill

# Validate skill structure and content
bun run validate:skill

Session Storage

Sessions are stored in platform-specific global locations:

• macOS: ~/Library/Application Support/auq/sessions
• Linux: ~/.local/share/auq/sessions (or $XDG_DATA_HOME/auq/sessions)
• Windows: %APPDATA%\auq\sessions

Can be customized with AUQ_SESSION_DIR environment variable.

AUQ can be configured via a .auqrc.json file. Settings are loaded from (in priority order):

1. Local: ./.auqrc.json (project directory)
2. Global: ~/.config/auq/.auqrc.json (or $XDG_CONFIG_HOME/auq/.auqrc.json)
3. Defaults: Built-in values

Settings from local config override global config, which overrides defaults.

Default Configuration

{
  "renderer": "opentui",
  "maxOptions": 5,
  "maxQuestions": 5,
  "recommendedOptions": 4,
  "recommendedQuestions": 4,
  "sessionTimeout": 0,
  "retentionPeriod": 604800000,
  "language": "auto",
  "theme": "system",
  "autoSelectRecommended": true,
  "updateCheck": true,
  "notifications": {
    "enabled": true,
    "sound": true
  }
}

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.

• 🎨 16 built-in themes + custom theme support
• 🌍 i18n (English, Korean) with auto-detection
• 📊 Dock progress bar (iTerm2, WezTerm, Ghostty)
• 🔤 Full CJK character support

Power Moves