auq-mcp-server 1.2.7 → 1.2.9

package/README.md

@@ -1,18 +1,22 @@
 ![AUQ Demo](media/demo.png)
 
-# AUQ - ask-user-questions MCP
+# AUQ - Ask User Questions
 
 [![npm version](https://img.shields.io/npm/v/auq-mcp-server.svg)](https://www.npmjs.com/package/auq-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=ask-user-questions&config=eyJlbnYiOnt9LCJjb21tYW5kIjoibnB4IC15IGF1cS1tY3Atc2VydmVyIHNlcnZlciJ9)
 
-**A lightweight MCP server & CLI tool that allows your LLMs to ask questions to you in a clean, separate space with great terminal UX. Made for multi-agent parallel coding workflows.**
+**A lightweight CLI tool that allows your LLMs to ask questions to you in a separate space with clean terminal UX. Supports both MCP server and official OpenCode plugin integration. Made for multi-agent parallel coding workflows.**
+
+🤔 [Why do I need it when I already have question tool in CC/OC?](#-why-auq-vs-built-in-ask-tools)
+
+[Setup](#setup-instructions) • [Features](#-features)
 
 ---
 
 ## What does it do?
 
-This MCP server lets your AI assistants generate clarifying questions consisting of multiple-choice/single-choice questions (with an "Other" option for custom input) while coding or working, and wait for your answers through a separate CLI tool without messing up your workflow.
+AUQ lets your AI assistants generate clarifying questions consisting of multiple-choice/single-choice questions (with an "Other" option for custom input) while coding or working, and wait for your answers through a separate CLI tool without messing up your workflow.
 
 You can keep the CLI running in advance, or start it when questions are pending. With simple arrow key navigation, you can select answers and send them back to the AI—all within a clean terminal interface.
 
@@ -22,7 +26,7 @@ In AI-assisted coding, guiding LLMs to ask **clarifying questions** have been wi
 
 On October 18th, Claude Code 2.0.21 introduced an internal `ask-user-question` tool. Inspired by it, I decided to build a similar tool that is:
 
-- **Tool-agnostic** - Works with any MCP client (Claude Desktop, Cursor, etc.)
+- **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
 
@@ -56,9 +60,42 @@ Recent AI workflows often use parallel sub-agents for concurrent coding. AUQ han
 
 ---
 
+## 🤔 Why AUQ vs. Built-in Ask Tools?
+
+**Why should I use AUQ instead of the built-in "Question" tools in OpenCode, Claude Code, or other coding agents?**
+
+AUQ is designed for the era of parallel multi-agent workflows, with several key advantages:
+
+### 🚀 Non-Blocking Parallel Operation
+Unlike built-in ask tools that halt the entire AI workflow until you respond, AUQ **doesn't block the AI from continuing work**. Questions are queued asynchronously, allowing your AI assistants to keep coding while you review and answer questions at your own pace.
+
+### 🎯 Multi-Agent Question Set Support
+**The killer feature**: AUQ can handle question sets from **multiple agents simultaneously**. In modern AI coding workflows, you often have several sub-agents working in parallel—each might need clarification on different aspects of your codebase. With AUQ:
+
+- **No more screen switching** between different agent conversations
+- **Unified queue** for all agent questions, regardless of which AI tool they're coming from
+- **Sequential processing** of questions from multiple sources in one interface
+
+### 🌐 Cross-Platform Question Aggregation
+AUQ's **unified data origin** means you can answer questions from **different AI clients simultaneously**:
+- Claude Code questions
+- OpenCode questions
+- Cursor/MCP questions
+
+All appear in the **same CLI interface**, creating a single source of truth for all AI-agent questions across your entire development environment.
+
+### 💡 Perfect for Parallel Agent Workflows
+As AI coding moves toward sophisticated multi-agent systems, AUQ becomes essential. Instead of managing blocking questions across multiple agent screens, you get one streamlined interface that handles questions from your entire AI coding ecosystem—keeping your focus on the code, not the coordination.
+
+**TL;DR**: AUQ transforms AI-agent questions from blocking interruptions into a smooth, unified workflow that scales with your AI coding setup.
+
+---
+
 # Setup Instructions
 
-## 🚀 Step 1: Setup CLI
+## 🚀 Install CLI Tool
+
+First, install the AUQ CLI tool:
 
 ### Global Installation (Recommended)
 
@@ -87,7 +124,11 @@ npx auq
 
 ---
 
-## 🔌 Step 2: Setup MCP Server
+## 🔌 Choose Your Integration Method
+
+AUQ supports multiple AI coding environments. Choose the one that fits your workflow:
+
+### Option A: MCP Server (Recommended for most users)
 
 ### Cursor
 
@@ -168,28 +209,30 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 **Restart Claude Desktop** after saving.
 
----
+### Option B: Official OpenCode Plugin
 
-## 🔌 OpenCode Plugin (Optional)
+We now have **official OpenCode plugin support**! We support OpenCode because OpenCode's MCP server seems to have some limitations (timeout), so we created an OpenCode-specific plugin that works perfectly together with OpenCode.
 
-If you want the OpenCode tool to call `auq ask` directly (without MCP), install
-the plugin package and add it to your OpenCode config.
+The OpenCode plugin allows OpenCode to call `auq ask` directly (without MCP), providing seamless integration with OpenCode's workflow.
+
+#### Installation
 
 ```bash
+# Install both CLI and plugin
 npm install -g auq-mcp-server
 npm install -g @paulp-o/opencode-auq
 ```
 
+#### Configuration
+
 Add to `opencode.json`:
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
   "plugin": ["@paulp-o/opencode-auq"]
 }
 ```
 
-The plugin assumes `auq` is available on `PATH` (global install or equivalent).
 
 ---
 

package/dist/bin/auq.js

@@ -3,14 +3,7 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { Box, render, Text } from "ink";
-import React, { useEffect, useState } from "react";
-import { ensureDirectoryExists, getSessionDirectory, } from "../src/session/utils.js";
-import { Header } from "../src/tui/components/Header.js";
-import { StepperView } from "../src/tui/components/StepperView.js";
-import { Toast } from "../src/tui/components/Toast.js";
-import { WaitingScreen } from "../src/tui/components/WaitingScreen.js";
-import { createTUIWatcher } from "../src/tui/session-watcher.js";
+import { getSessionDirectory } from "../src/session/utils.js";
 // import { goodbyeText } from "../src/tui/utils/gradientText.js";
 // Handle command-line arguments
 const args = process.argv.slice(2);
@@ -180,153 +173,11 @@ if (command === "ask") {
         process.exit(1);
     }
 }
-const App = () => {
-    const [state, setState] = useState({ mode: "WAITING" });
-    const [sessionQueue, setSessionQueue] = useState([]);
-    const [isInitialized, setIsInitialized] = useState(false);
-    const [toast, setToast] = useState(null);
-    const [showSessionLog, setShowSessionLog] = useState(true);
-    // Get session directory for logging
-    const sessionDir = getSessionDirectory();
-    // Auto-hide session log after 3 seconds
-    useEffect(() => {
-        const timer = setTimeout(() => {
-            setShowSessionLog(false);
-        }, 3000);
-        return () => clearTimeout(timer);
-    }, []);
-    // Initialize: Load existing sessions + start persistent watcher
-    useEffect(() => {
-        let watcherInstance = null;
-        const initialize = async () => {
-            try {
-                // Step 0: Ensure session directory exists
-                await ensureDirectoryExists(sessionDir);
-                // Step 1: Load existing pending sessions
-                const watcher = createTUIWatcher();
-                const sessionIds = await watcher.getPendingSessions();
-                const sessionData = await Promise.all(sessionIds.map(async (sessionId) => {
-                    const sessionRequest = await watcher.getSessionRequest(sessionId);
-                    if (!sessionRequest)
-                        return null;
-                    return {
-                        sessionId,
-                        sessionRequest,
-                        timestamp: new Date(sessionRequest.timestamp),
-                    };
-                }));
-                // Filter out null entries and sort by timestamp (FIFO - oldest first)
-                const validSessions = sessionData
-                    .filter((s) => s !== null)
-                    .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
-                setSessionQueue(validSessions);
-                setIsInitialized(true);
-                // Step 2: Start persistent watcher for new sessions
-                watcherInstance = createTUIWatcher({ autoLoadData: true });
-                watcherInstance.startEnhancedWatching((event) => {
-                    // Add new session to queue (FIFO - append to end)
-                    setSessionQueue((prev) => {
-                        // Check for duplicates
-                        if (prev.some((s) => s.sessionId === event.sessionId)) {
-                            return prev;
-                        }
-                        // Add to end of queue
-                        return [
-                            ...prev,
-                            {
-                                sessionId: event.sessionId,
-                                sessionRequest: event.sessionRequest,
-                                timestamp: new Date(event.timestamp),
-                            },
-                        ];
-                    });
-                });
-            }
-            catch (error) {
-                console.error("Failed to initialize:", error);
-                setIsInitialized(true); // Continue even if initialization fails
-            }
-        };
-        initialize();
-        // Cleanup: stop watcher on unmount
-        return () => {
-            if (watcherInstance) {
-                watcherInstance.stop();
-            }
-        };
-    }, []);
-    // Auto-transition: WAITING → PROCESSING when queue has items
-    useEffect(() => {
-        if (!isInitialized)
-            return;
-        if (state.mode === "WAITING" && sessionQueue.length > 0) {
-            const [nextSession, ...rest] = sessionQueue;
-            setSessionQueue(rest);
-            setState({ mode: "PROCESSING", session: nextSession });
-        }
-    }, [state, sessionQueue, isInitialized]);
-    // Show toast notification
-    const showToast = (message, type = "success", title) => {
-        setToast({ message, type, title });
-    };
-    // Handle session completion
-    const handleSessionComplete = (wasRejected = false, rejectionReason) => {
-        // Show appropriate toast
-        if (wasRejected) {
-            if (rejectionReason) {
-                showToast(`Rejection reason: ${rejectionReason}`, "info", "Question set rejected");
-            }
-            else {
-                showToast("", "info", "Question set rejected");
-            }
-        }
-        else {
-            showToast("✓ Answers submitted successfully!", "success");
-        }
-        if (sessionQueue.length > 0) {
-            // Auto-load next session
-            const [nextSession, ...rest] = sessionQueue;
-            setSessionQueue(rest);
-            setState({ mode: "PROCESSING", session: nextSession });
-        }
-        else {
-            // Return to WAITING
-            setState({ mode: "WAITING" });
-        }
-    };
-    // Render based on state
-    if (!isInitialized) {
-        return React.createElement(Text, null, "Loading...");
-    }
-    let mainContent;
-    if (state.mode === "WAITING") {
-        mainContent = React.createElement(WaitingScreen, { queueCount: sessionQueue.length });
-    }
-    else {
-        // PROCESSING mode
-        const { session } = state;
-        mainContent = (React.createElement(StepperView, { key: session.sessionId, onComplete: handleSessionComplete, sessionId: session.sessionId, sessionRequest: session.sessionRequest }));
-    }
-    // Render with header, toast overlay, and main content
-    return (React.createElement(Box, { flexDirection: "column", paddingX: 1 },
-        React.createElement(Header, { pendingCount: sessionQueue.length }),
-        toast && (React.createElement(Box, { marginBottom: 1, marginTop: 1 },
-            React.createElement(Toast, { message: toast.message, onDismiss: () => setToast(null), type: toast.type, title: toast.title }))),
-        mainContent,
-        showSessionLog && (React.createElement(Box, { marginTop: 1 },
-            React.createElement(Text, { dimColor: true },
-                "[AUQ] Session directory: ",
-                sessionDir)))));
-};
-// Clear terminal before showing app
-console.clear();
-const { waitUntilExit } = render(React.createElement(App, null));
-// Handle Ctrl+C gracefully
-process.on("SIGINT", () => {
-    process.exit(0);
-});
-// Show goodbye after Ink unmounts
-waitUntilExit().then(() => {
-    process.stdout.write("\n");
-    console.log("👋 Goodbye! See you next time.");
-});
+// Default: Start TUI
+// Important: Lazy-load Ink/React so non-interactive commands (ask/server) don't pull them in.
+// Also force production mode before importing React/Ink to avoid perf_hooks measure accumulation warnings.
+if (!process.env.NODE_ENV) {
+    process.env.NODE_ENV = "production";
+}
+const { runTui } = await import("./tui-app.js");
+runTui();

package/dist/bin/tui-app.js

@@ -0,0 +1,160 @@
+import { Box, render, Text } from "ink";
+import React, { useEffect, useState } from "react";
+import { ensureDirectoryExists, getSessionDirectory, } from "../src/session/utils.js";
+import { Header } from "../src/tui/components/Header.js";
+import { StepperView } from "../src/tui/components/StepperView.js";
+import { Toast } from "../src/tui/components/Toast.js";
+import { WaitingScreen } from "../src/tui/components/WaitingScreen.js";
+import { createTUIWatcher } from "../src/tui/session-watcher.js";
+const App = () => {
+    const [state, setState] = useState({ mode: "WAITING" });
+    const [sessionQueue, setSessionQueue] = useState([]);
+    const [isInitialized, setIsInitialized] = useState(false);
+    const [toast, setToast] = useState(null);
+    const [showSessionLog, setShowSessionLog] = useState(true);
+    // Get session directory for logging
+    const sessionDir = getSessionDirectory();
+    // Auto-hide session log after 3 seconds
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            setShowSessionLog(false);
+        }, 3000);
+        return () => clearTimeout(timer);
+    }, []);
+    // Initialize: Load existing sessions + start persistent watcher
+    useEffect(() => {
+        let watcherInstance = null;
+        const initialize = async () => {
+            try {
+                // Step 0: Ensure session directory exists
+                await ensureDirectoryExists(sessionDir);
+                // Step 1: Load existing pending sessions
+                const watcher = createTUIWatcher();
+                const sessionIds = await watcher.getPendingSessions();
+                const sessionData = await Promise.all(sessionIds.map(async (sessionId) => {
+                    const sessionRequest = await watcher.getSessionRequest(sessionId);
+                    if (!sessionRequest)
+                        return null;
+                    return {
+                        sessionId,
+                        sessionRequest,
+                        timestamp: new Date(sessionRequest.timestamp),
+                    };
+                }));
+                // Filter out null entries and sort by timestamp (FIFO - oldest first)
+                const validSessions = sessionData
+                    .filter((s) => s !== null)
+                    .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+                setSessionQueue(validSessions);
+                setIsInitialized(true);
+                // Step 2: Start persistent watcher for new sessions
+                watcherInstance = createTUIWatcher({ autoLoadData: true });
+                watcherInstance.startEnhancedWatching((event) => {
+                    // Add new session to queue (FIFO - append to end)
+                    setSessionQueue((prev) => {
+                        // Check for duplicates
+                        if (prev.some((s) => s.sessionId === event.sessionId)) {
+                            return prev;
+                        }
+                        // Add to end of queue
+                        return [
+                            ...prev,
+                            {
+                                sessionId: event.sessionId,
+                                sessionRequest: event.sessionRequest,
+                                timestamp: new Date(event.timestamp),
+                            },
+                        ];
+                    });
+                });
+            }
+            catch (error) {
+                console.error("Failed to initialize:", error);
+                setIsInitialized(true); // Continue even if initialization fails
+            }
+        };
+        initialize();
+        // Cleanup: stop watcher on unmount
+        return () => {
+            if (watcherInstance) {
+                watcherInstance.stop();
+            }
+        };
+    }, []);
+    // Auto-transition: WAITING → PROCESSING when queue has items
+    useEffect(() => {
+        if (!isInitialized)
+            return;
+        if (state.mode === "WAITING" && sessionQueue.length > 0) {
+            const [nextSession, ...rest] = sessionQueue;
+            setSessionQueue(rest);
+            setState({ mode: "PROCESSING", session: nextSession });
+        }
+    }, [state, sessionQueue, isInitialized]);
+    // Show toast notification
+    const showToast = (message, type = "success", title) => {
+        setToast({ message, type, title });
+    };
+    // Handle session completion
+    const handleSessionComplete = (wasRejected = false, rejectionReason) => {
+        // Show appropriate toast
+        if (wasRejected) {
+            if (rejectionReason) {
+                showToast(`Rejection reason: ${rejectionReason}`, "info", "Question set rejected");
+            }
+            else {
+                showToast("", "info", "Question set rejected");
+            }
+        }
+        else {
+            showToast("✓ Answers submitted successfully!", "success");
+        }
+        if (sessionQueue.length > 0) {
+            // Auto-load next session
+            const [nextSession, ...rest] = sessionQueue;
+            setSessionQueue(rest);
+            setState({ mode: "PROCESSING", session: nextSession });
+        }
+        else {
+            // Return to WAITING
+            setState({ mode: "WAITING" });
+        }
+    };
+    // Render based on state
+    if (!isInitialized) {
+        return React.createElement(Text, null, "Loading...");
+    }
+    let mainContent;
+    if (state.mode === "WAITING") {
+        mainContent = React.createElement(WaitingScreen, { queueCount: sessionQueue.length });
+    }
+    else {
+        // PROCESSING mode
+        const { session } = state;
+        mainContent = (React.createElement(StepperView, { key: session.sessionId, onComplete: handleSessionComplete, sessionId: session.sessionId, sessionRequest: session.sessionRequest }));
+    }
+    // Render with header, toast overlay, and main content
+    return (React.createElement(Box, { flexDirection: "column", paddingX: 1 },
+        React.createElement(Header, { pendingCount: sessionQueue.length }),
+        toast && (React.createElement(Box, { marginBottom: 1, marginTop: 1 },
+            React.createElement(Toast, { message: toast.message, onDismiss: () => setToast(null), type: toast.type, title: toast.title }))),
+        mainContent,
+        showSessionLog && (React.createElement(Box, { marginTop: 1 },
+            React.createElement(Text, { dimColor: true },
+                "[AUQ] Session directory: ",
+                sessionDir)))));
+};
+export const runTui = () => {
+    // Clear terminal before showing app
+    console.clear();
+    const { waitUntilExit } = render(React.createElement(App, null));
+    // Handle Ctrl+C gracefully
+    process.on("SIGINT", () => {
+        process.exit(0);
+    });
+    // Show goodbye after Ink unmounts
+    waitUntilExit().then(() => {
+        process.stdout.write("\n");
+        console.log("👋 Goodbye! See you next time.");
+    });
+};

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auq-mcp-server",
-    "version": "1.2.7",
+    "version": "1.2.9",
     "main": "dist/index.js",
     "bin": {
         "auq": "dist/bin/auq.js"

package/dist/src/tui/components/OptionsList.js

@@ -22,6 +22,15 @@ export const OptionsList = ({ isFocused, onSelect, options, selectedOption, show
     useInput((input, key) => {
         if (!isFocused)
             return;
+        // Handle up/down navigation even when custom input is focused
+        if (key.upArrow) {
+            setFocusedIndex((prev) => Math.max(0, prev - 1));
+            return;
+        }
+        if (key.downArrow) {
+            setFocusedIndex((prev) => Math.min(maxIndex, prev + 1));
+            return;
+        }
         // When custom input is focused, only handle escape to exit, let MultiLineTextInput handle other keys
         if (isCustomInputFocused) {
             if (key.escape) {
@@ -30,12 +39,6 @@ export const OptionsList = ({ isFocused, onSelect, options, selectedOption, show
             }
             return;
         }
-        if (key.upArrow) {
-            setFocusedIndex((prev) => Math.max(0, prev - 1));
-        }
-        if (key.downArrow) {
-            setFocusedIndex((prev) => Math.min(maxIndex, prev + 1));
-        }
         if (multiSelect) {
             // Multi-select mode
             if (input === " ") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auq-mcp-server",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "main": "dist/index.js",
   "bin": {
     "auq": "dist/bin/auq.js"