askq

askq

Native GUI for multiple-choice questions from AI coding agents. A blocking CLI (code --wait style): feed it the questions JSON, the user answers in a window, it prints the answers JSON to stdout and exits.

npm install -g askq-cli        # installs the `askq` command (macOS / Linux)
echo '{"questions":[{"question":"Pick","header":"Demo","multiSelect":false,
  "options":[{"label":"A"},{"label":"B"}]}]}' | askq
# => {"questions":[...],"answers":{"Pick":"A"}}

The package is askq-cli; the command it installs is askq. The right prebuilt binary (macOS arm64, Linux x64/arm64) is pulled in automatically as an optional dependency. No global install? npx -y askq-cli … works too.

Below, askq means that command. (To hack on it, build from source instead: cd src-tauri && cargo build --release → src-tauri/target/release/askq.)

---

1. CLI

Pipe the questions JSON to stdin (or pass --file <path>); read the answers from stdout. Exit 0 = answered, exit 1 = cancelled (window closed / Esc).

echo '{"questions":[ ... ]}' | askq
askq --file questions.json
askq --title "What I'm doing" --context "project · session"   # optional banner
askq --help        # full input/output schema — LLM-friendly

Input (stdin or --file): {"questions": [QUESTION, ...]} (a bare array also works). Each question:

{
  "question": "text shown; also the KEY in the answers map",   // required
  "header":   "short label, e.g. Framework",                    // optional
  "multiSelect": false,                                         // optional, default false
  "options": [
    { "label": "React",                  // required; this exact string is returned
      "description": "one-line detail",  // optional
      "preview": "monospace side-pane text shown on hover" }    // optional
  ]
}

Output (stdout, one line, exit 0): {"questions": [...echoed...], "answers": {"<question>": "<label>"}} — multiSelect joins chosen labels with ", "; a free-text "Other" answer returns the typed string.

---

2. MCP tool (agent-agnostic — recommended for Cursor/Codex/Gemini/…)

askq mcp runs a stdio MCP server exposing one tool, ask_user_question, whose input schema is the questions format above. Any MCP client can call it and gets the answers map back as the tool result.

Claude Code — .mcp.json (project) or ~/.claude.json (user):

{
  "mcpServers": {
    "askq": { "type": "stdio", "command": "askq", "args": ["mcp"] }
  }
}

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "askq": { "command": "askq", "args": ["mcp"] }
  }
}

Codex, Gemini CLI, and other MCP clients use their own config files but the same {command, args:["mcp"]} shape. (askq requires npm i -g askq-cli; or use { "command": "npx", "args": ["-y", "askq-cli", "mcp"] } to skip the install.)

---

3. Claude Code PreToolUse hook (replaces the native picker)

Claude Code is the only agent with a native AskUserQuestion tool and the PreToolUse → allow + updatedInput round-trip that lets a hook feed answers back into the model. The hook (plugin/hooks/askq-pretooluse.sh, requires jq) ships in the plugin (plugin/), which declares it via ${CLAUDE_PLUGIN_ROOT} — no absolute paths to hand-wire:

npm install -g askq-cli          # provides the `askq` command (or rely on npx)
claude --plugin-dir ./plugin     # loads hook + MCP tool + skill for the session

The plugin runs askq through plugin/bin/askq-run, which prefers a global askq, falls back to npx askq-cli, and honors $ASKQ_BIN (point it at a locally-built binary when developing). On cancel the hook returns permissionDecision: "ask", so Claude falls back to the native picker.

---

Why two paths (cross-agent note)

Other agents (Cursor, Codex, Gemini, …) have no AskUserQuestion tool, and their hooks are mostly fire-and-forget notifications that can't inject a structured answer back into the conversation. So the hook approach (method 3) is Claude-Code-specific; for every other agent the MCP tool (method 2) is the portable way — the agent calls ask_user_question directly.

A Claude Code plugin that bundles all three (MCP server, PreToolUse hook, and skill behind ${CLAUDE_PLUGIN_ROOT}, no absolute paths) lives in plugin/. It runs askq via the published askq-cli (global askq or npx), so there's no binary to ship. Validate with claude plugin validate ./plugin --strict, or load it for a session with claude --plugin-dir ./plugin.

See CLAUDE.md for the architecture, the exact hook contract, and the interactive-mode caveat that still needs verifying.