Skip to content
Back to search

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!

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/paulp-o--ask-user-questions-mcp/badge.svg)](/listings/paulp-o--ask-user-questions-mcp)

HTML

<a href="/listings/paulp-o--ask-user-questions-mcp"><img src="/api/listings/paulp-o--ask-user-questions-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

πŸš€ 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.

<details><summary>Local (Project-specific) Installation</summary>

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

Sessions are stored **globally** regardless of installation method. See [Troubleshooting](#troubleshooting) for session locations.

</details>

---

πŸ”Œ 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._

<details> <summary><strong>Cursor</strong></summary>

</details>

<details> <summary><strong>Claude Code</strong></summary>

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

</details>

<details> <summary><strong>Codex CLI</strong></summary>

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

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

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.

</details>

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.

<details> <summary><strong>Limitations</strong></summary>

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.

</details>

---

πŸ’» 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).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 830 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![AUQ Demo](media/demo2.png)
  2. # AUQ - Ask User Questions
  3. _`AskUserQuestion` pushed to the max_
  4. <img src="media/icon.png" alt="AUQ Logo" width="120" />
  5. [![npm version](https://img.shields.io/npm/v/auq-mcp-server.svg)](https://www.npmjs.com/package/auq-mcp-server)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=ask-user-questions&config=eyJlbnYiOnt9LCJjb21tYW5kIjoibnB4IC15IGF1cS1tY3Atc2VydmVyIHNlcnZlciJ9)
  8. **A complete toolset that enables maximum level of human-(intention-)in-the-loop onto any long-running, multi-agentic AI workflows (like Ralph Loop!).**
  9. 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!
  10. **Can be used via MCP server / OpenCode plugin / Agent Skills.**
  11. [Setup](#-install-cli-tool) β€’ [Usage](#-usage)
  12. > πŸ€” [I already have question tool in CC/OC/Cursor. Why use this?](#-why-auq-vs-built-in-questioning-tools)
  13. ---
  14. ## What does it do?
  15. 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.
  16. 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**!
  17. <details>
  18. <summary><i>A no no fun background story</i></summary>
  19. 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].
  20. 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:
  21. - **Integration-flexible** - Works with MCP clients (Claude Desktop, Cursor, etc.) and has official OpenCode plugin support
  22. - **Non-invasive** - Doesn't heavily integrate with your coding CLI workflow or occupy UI space
  23. - **Multi-agent friendly** - Supports receiving questions from multiple agents simultaneously in parallel workflows
  24. </details>
  25. ---
  26. ## ✨ Demo
  27. <https://github.com/user-attachments/assets/3a135a13-fcb1-4795-9a6b-f426fa079674>
  28. ---
  29. # Setup Instructions
  30. ## πŸš€ Install CLI Tool
  31. First, install the **AUQ CLI**:
  32. ### Global Installation (Recommended)
  33. **Bun (recommended β€” required for default OpenTUI renderer)**
  34. ```bash
  35. bun add -g auq-mcp-server
  36. ```
  37. **npm**
  38. ```bash
  39. npm install -g auq-mcp-server
  40. ```
  41. **pnpm**
  42. ```bash
  43. pnpm add -g auq-mcp-server
  44. ```
  45. **yarn**
  46. ```bash
  47. yarn global add auq-mcp-server
  48. ```
  49. > **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.
  50. <details><summary>Local (Project-specific) Installation</summary>
  51. ```bash
  52. # Install in your project
  53. bun add auq-mcp-server
  54. ```
  55. Sessions are stored **globally** regardless of installation method. See [Troubleshooting](#troubleshooting) for session locations.
  56. </details>
  57. ---
  58. ## πŸ”Œ Integrate to your AI
  59. AUQ supports multiple AI environments. Choose between **OpenCode plugin** and **MCP server**.
  60. ### Option A: MCP Server
  61. > _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._
  62. <details>
  63. <summary><strong>Cursor</strong></summary>
  64. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ask-user-questions&config=eyJlbnYiOnt9LCJjb21tYW5kIjoibnB4IC15IGF1cS1tY3Atc2VydmVyIHNlcnZlciJ9)
  65. </details>
  66. <details>
  67. <summary><strong>Claude Code</strong></summary>
  68. **Method 1: Using CLI** (Recommended)
  69. ```bash
  70. claude mcp add --transport stdio ask-user-questions -- bunx -y auq-mcp-server server
  71. ```
  72. > **Note:** `npx` also works if you prefer npm.
  73. **Method 2: Manual Configuration**
  74. Add to `.mcp.json` in your project root (for team-wide sharing):
  75. ```json
  76. {
  77. "mcpServers": {
  78. "ask-user-questions": {
  79. "type": "stdio",
  80. "command": "bunx",
  81. "args": ["-y", "auq-mcp-server", "server"]
  82. }
  83. }
  84. }
  85. ```
  86. Or add to `~/.claude.json` for global access across all projects.
  87. _**Note:** Replace `bunx` if you don't use bun._
  88. **Verify setup:** Type `/mcp` in Claude Code to check server status.
  89. </details>
  90. <details>
  91. <summary><strong>Codex CLI</strong></summary>
  92. Add to `~/.codex/config.toml`:
  93. ```toml
  94. [mcp_servers.ask-user-questions]
  95. command = "bunx"
  96. args = ["-y", "auq-mcp-server", "server"]
  97. tool_timeout_sec = 99999 // Extend timeout for long sessions
  98. ```
  99. </details>
  100. <details>
  101. <summary><strong>Claude Desktop</strong></summary>
  102. Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  103. ```json
  104. {
  105. "mcpServers": {
  106. "ask-user-questions": {
  107. "command": "bunx",
  108. "args": ["-y", "auq-mcp-server", "server"]
  109. }
  110. }
  111. }
  112. ```
  113. > _Replace `bunx` if you don't use bun._
  114. **Restart Claude Desktop** after saving.
  115. </details>
  116. ### Option B: OpenCode Plugin
  117. **Direct integration** for OpenCode users. Adds working directory viewability feature exclusively.
  118. #### Configuration
  119. Add to `opencode.json`:
  120. ```json
  121. {
  122. "plugin": ["@paulp-o/opencode-auq@latest"]
  123. }
  124. ```
  125. ### Option C: Agent Skills (Experimental)
  126. #### Usage with Skills-Compatible Agents
  127. Copy the `skills/ask-user-questions/` folder to your agent's skills directory.
  128. <details>
  129. <summary><strong>Limitations</strong></summary>
  130. 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.
  131. </details>
  132. ---
  133. ## πŸ’» Usage
  134. ### Starting the CLI tool
  135. ```bash
  136. auq # if installed globally (bun add -g)
  137. # bunx auq
  138. # npx auq
  139. ```
  140. Start by defining your workflow to use AUQ tool for clarifying questions, on `AGENTS.md` (or `CLAUDE.md`), like:
  141. ```markdown
  142. Whenever you need clarification on what you are working on, never guess, and call AUQ(ask-user-questions).
  143. ```
  144. When the AI asks questions, you'll see them appear in the AUQ TUI. Answer them **at your convenience**.
  145. ### Renderer Selection
  146. AUQ supports two terminal rendering engines:
  147. | Renderer | Description | Status |
  148. | --------------------- | --------------------------------------------------- | ------------------- |
  149. | **OpenTUI** (default) | Native Zig-based renderer with improved performance | Stable (requires Bun) |
  150. | **ink** | React-based terminal renderer | Fallback (Node.js) |
  151. OpenTUI is the default renderer and requires **Bun** runtime. When Bun is unavailable, AUQ automatically falls back to the Ink renderer.
  152. **To force a specific renderer**, set one of the following (in priority order):
  153. 1. **Environment variable** (highest priority):
  154. ```bash
  155. AUQ_RENDERER=ink auq # force ink
  156. AUQ_RENDERER=opentui auq # force opentui
  157. ```
  158. 2. **Config file** (`.auqrc.json`):
  159. ```json
  160. {
  161. "renderer": "ink"
  162. }
  163. ```
  164. 3. **CLI command**:
  165. ```bash
  166. auq config set renderer ink
  167. ```
  168. > **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.
  169. ### Markdown rendering in question prompts
  170. Question prompts now support **Markdown formatting** in the `prompt` text.
  171. - Supported: **bold**, _italic_, ~~strikethrough~~, `inline code`, links, and fenced code blocks (with syntax highlighting)
  172. - Links render as `text (url)` for broad terminal compatibility
  173. - Code blocks use theme-aware colors (background/text/border)
  174. - Always enabled (no configuration needed)
  175. - Plain text prompts pass through unchanged
  176. - Graceful fallback: if Markdown parsing fails, the raw text is shown
  177. > _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._
  178. > _I personally enjoy prompting it to ask at least 30 questions repeatedly before action!_
  179. ### Recommended Setups
  180. 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.
  181. ### Useful Keyboard Shortcuts
  182. | Key | Action | Description |
  183. | -------- | ------------- | ------------------------------------------------------------------ |
  184. | `Space` | Select | Select/toggle option without advancing |
  185. | `Enter` | Select & Next | Select option and advance to next question |
  186. | `R` | Recommended | Select recommended option(s) for current question |
  187. | `Ctrl+R` | Quick Submit | Auto-select recommended options for all questions and go to review |
  188. | `Esc` | Reject | Reject the whole question set and optionally explain why to the AI |
  189. | `Ctrl+T` | Theme | Cycle through available color themes |
  190. | `[`/`]` | Sessions | Switch to previous/next session (OpenTUI: also click session dots) |
  191. **Mouse Support (OpenTUI renderer only):**
  192. | Action | Description |
  193. | ----------------- | ----------------------------------------------- |
  194. | Click option | Select/toggle option |
  195. | Scroll | Scroll through session picker or update overlay |
  196. | Click session dot | Switch to that session |
  197. <details>
  198. <summary><strong>⌨️ All Keyboard Shortcuts</strong></summary>
  199. | Key | Action |
  200. | -------- | ------------------------------------------------------------------ |
  201. | `↑↓` | Navigate options |
  202. | `←→/Tab` | Switch between questions |
  203. | `Space` | Select/toggle option without advancing |
  204. | `Enter` | Select option and advance to next question |
  205. | `R` | Select recommended option(s) for current question |
  206. | `Ctrl+R` | Quick submit β€” auto-fill recommended, go to review |
  207. | `Esc` | Reject the whole question set and optionally explain why |
  208. | `Ctrl+T` | Cycle through available color themes |
  209. | `Ctrl+S` | Open session picker |
  210. | `1-9` | Jump directly to session by number |
  211. | `[/]` | Navigate between sessions |
  212. | `U` | Open update overlay (when update available) |
  213. </details>
  214. <details>
  215. <summary><strong>More Commands (advanced)</strong></summary>
  216. ```bash
  217. # you won't likely need these at all
  218. auq server # Start MCP server
  219. auq --version # Show version
  220. auq update # Check for and install updates
  221. auq --help # Show help
  222. ```
  223. </details>
  224. ---
  225. <details>
  226. <summary><strong>πŸ“‹ Full CLI Reference</strong></summary>
  227. ### CLI Commands
  228. AUQ provides headless CLI commands for managing sessions and configuration without the TUI.
  229. Run `auq --help` for the complete reference.
  230. #### Answer Sessions
  231. ```bash
  232. auq answer <sessionId> --answers '{"0": {"selectedOption": "option1"}}'
  233. auq answer <sessionId> --answers '{"0": {"selectedOptions": ["A", "B"]}}' # multi-select
  234. auq answer <sessionId> --answers '{"0": {"customText": "free text"}}' # custom text
  235. auq answer <sessionId> --reject --reason "Not applicable"
  236. auq answer <sessionId> --answers '...' --force # abandoned session
  237. auq answer <sessionId> --answers '...' --json
  238. ```
  239. #### Manage Sessions
  240. ```bash
  241. auq sessions list # pending sessions (default)
  242. auq sessions list --stale # stale sessions only
  243. auq sessions list --all # all sessions
  244. auq sessions show <sessionId> # session details
  245. auq sessions dismiss <sessionId> # dismiss stale session
  246. auq sessions dismiss <sessionId> --force
  247. auq sessions list --limit 10 --page 2 # pagination
  248. auq sessions list --json
  249. ```
  250. #### Session History
  251. ```bash
  252. auq history # list session history
  253. auq history --all # include abandoned
  254. auq history --unread # unread only
  255. auq history --search "deploy" # search
  256. auq history --limit 10 --page 2 # pagination
  257. auq history show <sessionId> # full Q&A detail
  258. auq history --json
  259. ```
  260. #### Fetch Answers (Programmatic)
  261. ```bash
  262. auq fetch-answers --unread # list unread answered sessions
  263. auq fetch-answers <sessionId> # fetch specific session
  264. auq fetch-answers <sessionId> --blocking # wait until answered
  265. auq fetch-answers --limit 10 --page 2
  266. auq fetch-answers --json
  267. ```
  268. #### Configuration
  269. ```bash
  270. auq config get # view all
  271. auq config get staleThreshold # view specific
  272. auq config set staleThreshold 3600000 # set local
  273. auq config set staleThreshold 3600000 --global # set global
  274. ```
  275. #### Update
  276. ```bash
  277. auq update # interactive update check
  278. auq update -y # skip confirmation
  279. ```
  280. #### Pagination
  281. List commands (`sessions list`, `history`, `fetch-answers`) support:
  282. - `--limit <N>` β€” Max items per page (default: 20)
  283. - `--page <N>` β€” Page number (default: 1)
  284. </details>
  285. <details>
  286. <summary><strong>🌍 Environment Variables</strong></summary>
  287. | Variable | Description |
  288. | -------------------- | ------------------------------------------------ |
  289. | `AUQ_RENDERER` | Override renderer (`"ink"` or `"opentui"`) |
  290. | `AUQ_SESSION_DIR` | Custom session storage directory |
  291. | `XDG_CONFIG_HOME` | Custom config directory (default: `~/.config`) |
  292. | `NO_UPDATE_NOTIFIER` | Set to `"1"` to disable update checks |
  293. </details>
  294. ### Stale Session Detection
  295. 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.
  296. - **Visual indicators**: Stale sessions show a ⚠ warning icon and yellow highlighting in the TUI
  297. - **Toast notifications**: A notification appears when a session becomes stale (configurable)
  298. - **Grace period**: Interacting with a stale session provides a 30-minute grace period
  299. - **Configurable threshold**: Default is 2 hours (7,200,000ms)
  300. ---
  301. ### Abandoned Session Handling
  302. When an AI client disconnects, associated sessions are marked as "abandoned". These sessions:
  303. - Remain visible in the TUI with a red indicator
  304. - Show a confirmation dialog before answering ("AIκ°€ disconnectλ˜μ—ˆμŠ΅λ‹ˆλ‹€")
  305. - Can still be answered via CLI with the `--force` flag
  306. - Are detectable via `auq sessions list --all`
  307. ---
  308. ### Auto-Update
  309. AUQ automatically checks for updates and keeps itself up to date.
  310. #### How it works
  311. - **All updates** (patch, minor, major): A fullscreen overlay is shown with changelog and options to update, skip, or defer.
  312. - **Update checks**: Run on every TUI launch (no delay/cache).
  313. - **CLI notification**: When running non-TUI commands, a one-line update notification is shown if a newer version is available.
  314. #### Manual update
  315. Run `auq update` to manually check for and install updates:
  316. ```bash
  317. auq update # Interactive update check
  318. auq update -y # Skip confirmation prompt
  319. ```
  320. #### Disabling update checks
  321. Disable automatic update checks via config:
  322. ```bash
  323. auq config set updateCheck false
  324. ```
  325. Or set the environment variable:
  326. ```bash
  327. NO_UPDATE_NOTIFIER=1 auq ask "question"
  328. ```
  329. Update checks are automatically disabled in CI environments (`CI=true`).
  330. The `auq update` command always works regardless of these settings.
  331. ### Theme System
  332. AUQ supports **16 built-in color themes** with automatic persistence. Press `Ctrl+T` to cycle through themes.
  333. #### Theme Differences by Renderer
  334. | Feature | ink | OpenTUI |
  335. | ---------------- | ------------------ | ----------------------------------------- |
  336. | Header text | Gradient animation | Solid accent color |
  337. | Toast animations | `setTimeout` based | `useTimeline` based |
  338. | Markdown syntax | Basic highlighting | Tree-sitter powered |
  339. | Mouse support | No | Yes (click options, scroll, session dots) |
  340. > Both renderers support all 16 built-in themes and custom themes. Colors are consistent; only implementation details differ.
  341. <details>
  342. <summary><strong>Built-in Themes</strong></summary>
  343. | Theme | Style |
  344. | ---------------- | ------------------------ |
  345. | AUQ dark | Default dark theme |
  346. | AUQ light | Default light theme |
  347. | Nord | Arctic, bluish |
  348. | Dracula | Dark purple/pink |
  349. | Catppuccin Mocha | Warm dark pastels |
  350. | Catppuccin Latte | Warm light pastels |
  351. | Solarized Dark | Low contrast dark |
  352. | Solarized Light | Low contrast light |
  353. | Gruvbox Dark | Retro groove dark |
  354. | Gruvbox Light | Retro groove light |
  355. | Tokyo Night | Dark with vibrant colors |
  356. | One Dark | Atom-inspired dark |
  357. | Monokai | Classic vibrant dark |
  358. | GitHub Dark | GitHub's dark mode |
  359. | GitHub Light | GitHub's light mode |
  360. | RosΓ© Pine | Warm, cozy pinks |
  361. </details>
  362. Your selected theme is **automatically saved** to `~/.config/auq/config.json` and restored on next launch.
  363. <details>
  364. <summary><strong>Custom Themes</strong></summary>
  365. Create custom themes by placing `.theme.json` files in:
  366. - **macOS/Linux**: `~/.config/auq/themes/`
  367. Example custom theme (`~/.config/auq/themes/my-theme.theme.json`):
  368. ```json
  369. {
  370. "name": "my-theme",
  371. "colors": {
  372. "primary": "#ff6b6b",
  373. "success": "#51cf66",
  374. "text": "#f8f9fa"
  375. }
  376. }
  377. ```
  378. Custom themes inherit from the default dark themeβ€”only override the colors you want to change. See the [JSON schema](schemas/theme.schema.json) for all available properties.
  379. </details>
  380. ---
  381. ### Manual session cleanup
  382. Sessions auto-clean after retention period. However, you can manually clean them up if you want to.
  383. ```bash
  384. rm -rf ~/Library/Application\ Support/auq/sessions/* # macOS
  385. rm -rf ~/.local/share/auq/sessions/* # Linux
  386. ```
  387. ---
  388. <details>
  389. <summary><strong>Local Development & Testing</strong></summary>
  390. To test the MCP server and CLI locally during development:
  391. ### 1. Start the MCP Server (Terminal 1)
  392. ```bash
  393. # Option A: Run with tsx (recommended for development)
  394. bun run start
  395. # Option B: Run with fastmcp dev mode (includes web inspector at http://localhost:6274)
  396. bun run dev
  397. # Option C: Run the built version
  398. bun run build && bun run server
  399. ```
  400. ### 2. Create a Test Session (Terminal 2)
  401. Use the `auq ask` command to create a session and wait for answers:
  402. ```bash
  403. # Run directly with bun during development
  404. bun run bin/auq.tsx ask '{"questions": [{"prompt": "Which language?", "title": "Lang", "options": [{"label": "TypeScript"}, {"label": "Python"}], "multiSelect": false}]}'
  405. # Or pipe JSON to stdin
  406. echo '{"questions": [{"prompt": "Which database?", "title": "DB", "options": [{"label": "PostgreSQL"}, {"label": "MongoDB"}], "multiSelect": false}]}' | bun run bin/auq.tsx ask
  407. ```
  408. This will create a session and wait for the TUI to provide answers.
  409. ### 3. Answer with the TUI (Terminal 3)
  410. ```bash
  411. # Run the TUI to answer pending questions
  412. bun run bin/auq.tsx
  413. ```
  414. ### Create Mock Sessions for TUI Testing
  415. To test the TUI with multiple pending sessions:
  416. ```bash
  417. # Create 3 mock sessions (default)
  418. bun run scripts/create-mock-session.ts
  419. # Create a specific number of sessions
  420. bun run scripts/create-mock-session.ts 5
  421. ```
  422. Then run the TUI to see and answer them:
  423. ```bash
  424. bun run bin/auq.tsx
  425. ```
  426. ### Verify MCP and CLI Use Same Session Directory
  427. Both components should report the same session directory path. Check the logs:
  428. - MCP server logs session directory on startup
  429. - `auq ask` prints `[AUQ] Session directory: <path>` to stderr
  430. On macOS, both should use: `~/Library/Application Support/auq/sessions`
  431. ### Development Commands
  432. ```bash
  433. # Regenerate the skill from source
  434. bun run generate:skill
  435. # Validate skill structure and content
  436. bun run validate:skill
  437. ```
  438. </details>
  439. <details>
  440. <summary><strong>Troubleshooting</strong></summary>
  441. ### Session Storage
  442. Sessions are stored in platform-specific global locations:
  443. - **macOS**: `~/Library/Application Support/auq/sessions`
  444. - **Linux**: `~/.local/share/auq/sessions` (or `$XDG_DATA_HOME/auq/sessions`)
  445. - **Windows**: `%APPDATA%\auq\sessions`
  446. _Can be customized with `AUQ_SESSION_DIR` environment variable._
  447. </details>
  448. <details>
  449. <summary><strong>Configuration</strong></summary>
  450. AUQ can be configured via a `.auqrc.json` file. Settings are loaded from (in priority order):
  451. 1. **Local**: `./.auqrc.json` (project directory)
  452. 2. **Global**: `~/.config/auq/.auqrc.json` (or `$XDG_CONFIG_HOME/auq/.auqrc.json`)
  453. 3. **Defaults**: Built-in values
  454. _Settings from local config override global config, which overrides defaults._
  455. ### Default Configuration
  456. ```json
  457. {
  458. "renderer": "opentui",
  459. "maxOptions": 5,
  460. "maxQuestions": 5,
  461. "recommendedOptions": 4,
  462. "recommendedQuestions": 4,
  463. "sessionTimeout": 0,
  464. "retentionPeriod": 604800000,
  465. "language": "auto",
  466. "theme": "system",
  467. "autoSelectRecommended": true,
  468. "updateCheck": true,
  469. "notifications": {
  470. "enabled": true,
  471. "sound": true
  472. }
  473. }
  474. ```
  475. <details>
  476. <summary><strong>Available Settings</strong></summary>
  477. | Setting | Type | Default | Range/Values | Description |
  478. | ----------------------- | ------- | --------- | ------------------------------- | ----------------------------------------------------- |
  479. | `renderer` | string | "opentui" | "ink", "opentui" | Terminal rendering engine (OpenTUI default, ink fallback) |
  480. | `maxOptions` | number | 5 | 2-10 | Maximum options per question |
  481. | `maxQuestions` | number | 5 | 1-10 | Maximum questions per session |
  482. | `recommendedOptions` | number | 4 | 1-10 | Suggested number of options (for AI guidance) |
  483. | `recommendedQuestions` | number | 4 | 1-10 | Suggested number of questions (for AI guidance) |
  484. | `language` | string | "auto" | "auto", "en", "ko" | UI language (auto-detects from system if "auto") |
  485. | `theme` | string | "system" | "system", "dark", "light", etc. | Color theme for TUI |
  486. | `sessionTimeout` | number | 0 | 0+ (milliseconds) | Session timeout (0 = no timeout) |
  487. | `retentionPeriod` | number | 604800000 | 0+ (milliseconds) | How long to keep completed sessions (default: 7 days) |
  488. | `notifications.enabled` | boolean | true | true/false | Enable desktop notifications for new questions |
  489. | `notifications.sound` | boolean | true | true/false | Play sound with notifications |
  490. | `staleThreshold` | number | 7200000 | 0+ (milliseconds) | Time before a session is considered stale (2 hours) |
  491. | `notifyOnStale` | boolean | true | true/false | Show toast notification when sessions become stale |
  492. | `staleAction` | string | "warn" | "warn", "remove", "archive" | Action for stale sessions |
  493. | `updateCheck` | boolean | true | true/false | Enable automatic update checks on startup |
  494. </details>
  495. ### Language Support
  496. AUQ supports multiple languages for the TUI interface:
  497. - **English** (`en`) - Default
  498. - **Korean** (`ko`) - ν•œκ΅­μ–΄
  499. Language is auto-detected from system locale (`LANG`, `LC_ALL`, `LC_MESSAGES` environment variables) when set to `"auto"`.
  500. ### Desktop Notifications
  501. AUQ uses native desktop notifications to alert you when new questions arrive.
  502. #### Platform Requirements
  503. | Platform | Status | Notes |
  504. | -------- | ----------------------- | --------------------------------------------- |
  505. | macOS | βœ… Works out of the box | Uses Notification Center |
  506. | Windows | βœ… Works out of the box | Uses Action Center |
  507. | Linux | ⚠️ Requires libnotify | Install: `sudo apt-get install libnotify-bin` |
  508. Notifications can be disabled in configuration if needed.
  509. **Features:**
  510. - **Batched Notifications**: Rapid session arrivals are batched into a single notification
  511. - **Progress Bar**: Shows question completion progress in terminal dock icon (supported terminals like iTerm2 and WezTerm)
  512. - **Native Integration**: Uses system-native notification centers
  513. **Configuration:**
  514. ```json
  515. {
  516. "notifications": {
  517. "enabled": true,
  518. "sound": true
  519. }
  520. }
  521. ```
  522. - `notifications.enabled` (default: `true`): Enable desktop notifications
  523. - `notifications.sound` (default: `true`): Play sound with notifications
  524. Set `notifications.enabled` to `false` to disable all notifications.
  525. </details>
  526. ---
  527. ## πŸ€” Why AUQ vs. Built-in Questioning Tools?
  528. > **A clean decision inbox so you & AI stay in flow.**
  529. 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.
  530. ```
  531. Claude Code Cursor OpenCode
  532. β”‚ β”‚ β”‚
  533. β–Ό β–Ό β–Ό
  534. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  535. β”‚ πŸ“₯ AUQ Inbox β”‚
  536. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  537. β”‚
  538. β–Ό
  539. πŸ–₯️ TUI
  540. β”‚
  541. β–Ό
  542. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  543. β”‚ Your Answers β”‚
  544. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  545. β”‚ β”‚ β”‚
  546. β–Ό β–Ό β–Ό
  547. Claude Code Cursor OpenCode
  548. ```
  549. πŸ“₯ **One Inbox for All Agents** β€” Multiple agents ask in one place. One queue, one source of truth.
  550. 🧠 **Teach the AI** β€” Reject bad questions and tell it why. Turn "no" into better follow-ups.
  551. ❓ **Fix the Question First** β€” Can't answer because it's vague? Request **elaboration** before you guess.
  552. ⚑ **Blast Through the Obvious** β€” `Ctrl+R` accepts all **recommended** options. Focus on the hard decisions.
  553. πŸ”” **Pinged When It Matters** β€” Native notifications, **batched** so you're not spammed.
  554. 🌐 **Works Where You Work** β€” SSH into a remote server? AUQ runs there too.
  555. <details>
  556. <summary><strong>Nice Extras</strong></summary>
  557. - 🎨 16 built-in themes + custom theme support
  558. - 🌍 i18n (English, Korean) with auto-detection
  559. - πŸ“Š Dock progress bar (iTerm2, WezTerm, Ghostty)
  560. - πŸ”€ Full CJK character support
  561. #### Power Moves
  562. | Shortcut | What it does |
  563. | -------- | -------------------------------------------------- |
  564. | `Space` | Select option without advancing |
  565. | `Enter` | Select option and advance to next question |
  566. | `R` | Select recommended option(s) for current question |
  567. | `Ctrl+R` | Quick submit β€” auto-fill recommended, go to review |
  568. | `Esc` | Reject question set β€” optionally explain why |
  569. | `Ctrl+T` | Cycle through 16 themes |
  570. </details>
  571. ---
  572. ## πŸ“„ License
  573. MIT License - see [LICENSE](LICENSE) file for details.
  574. ---
  575. [1] arXiv:2308.13507 <https://arxiv.org/abs/2308.13507>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.