questionme

Questions from an AI agent, answered on your phone.

When an agent has more than a few questions for you, a chat makes you answer them one at a time, in a hurry, without pictures. questionme lets the agent write them all down: dozens or hundreds, grouped, with a recommendation for each, why it matters, and what you need to see to decide (files, proposed code, diffs, diagrams, mockups). You answer on your phone, at your own pace, on the same network. Your answers are saved in the project, and the agent reads only what's new.

npx questionme init     # once per project: the folder, the MCP server for Claude Code, a note in CLAUDE.md
npx questionme          # the page, for every project, with links for your phone

How it goes

1. The agent asks. It adds questions to a set (with the MCP tools, or by writing .questionme/sets/<set>.json) and gives you the link.

2. You answer, on your phone. Tap an option, or write your own. Add a note. Say You decide (take the recommendation), Later, or Skip. Ask why on any question; the agent can answer there. Picking an option can open follow-up questions. Answers save as you go.

3. The agent reads what's new. get_answers returns only answers since it last read, one line each, so 300 answers don't flood its context. It applies them and marks each applied with a note you see under the answer.

4. It doesn't have to sit and wait. The agent runs npx questionme wait <set> --blocking in the background and keeps working; the command exits, waking it, once you've answered what it needs.

Related MCP server: Joxo

For Claude Code (and other agents)

npx questionme init in a project:

• makes .questionme/ (sets and answers live here; commit them if you like),

• adds the MCP server to Claude Code for all your projects (claude mcp add --scope user questionme -- npx -y questionme@latest mcp),

• adds a short section to the project's CLAUDE.md (or AGENTS.md) on when and how to use it,

• with --hook, adds a hook that tells Claude about new answers whenever you send it a message.

The MCP server tells Claude when to use it (more than about 4 questions, questions that need thought or pictures, or ones that can be answered while it works) and how.

MCP tools

The CLI does the same

npx questionme list                              # sets, with counts
npx questionme show <set> [--full]               # the questions, one line each
npx questionme answers <set> --new               # what's new since the agent last read (marks it read; --peek doesn't)
npx questionme answers <set> --open              # what's still to answer, with the recommendations
npx questionme wait <set> --blocking             # exit once the blocking questions are answered, printing the new answers
npx questionme wait <set> --any --settle 60s     # exit once there are new answers and a minute has passed without more
npx questionme ack <set> <id…> --note "Done in src/x.ts"
npx questionme reply <set> <id> "Because the API bills per call."
npx questionme validate                          # check every set against the format
npx questionme schema                            # the format, as JSON Schema
npx questionme hook                              # one line per set with news (for a Claude Code hook; silent otherwise)
npx questionme notify ntfy                       # push notifications to your phone (see below)

wait is the seamless part: an agent starts it as a background command, carries on, and is woken when it exits.

The format

A set is a JSON file, .questionme/sets/<set>.json. The schema is in schema/set.schema.json ("$schema": "https://unpkg.com/questionme/schema/set.schema.json" gets you completion in an editor).

{
  "title": "Weather app: first plan",
  "intro": "I read `docs/plan.md`. **Blocking** ones stop me.",
  "sections": [
    {
      "id": "basics",
      "title": "The basics",
      "questions": [
        {
          "id": "platform",
          "question": "Where should the first version run?",
          "why": "Decides the toolkit and how alerts work.",
          "blocking": true,
          "options": [
            { "id": "web", "label": "A web app", "description": "One codebase.", "recommended": true },
            { "id": "native", "label": "Native apps", "description": "Two stores.", "shows": ["stores"] }
          ]
        },
        {
          "id": "stores",
          "question": "Which store first?",
          "hidden": true,
          "options": ["App Store", "Google Play"]
        }
      ]
    }
  ]
}

Questions

Showing and hiding

Every question and section is shown unless it says "hidden": true. Then:

• An option's shows lists questions or sections to show while it's picked. hides lists ones to hide (hiding wins).

• showIf shows a question or section only while a condition holds: { "question": "platform", "any": ["native", "both"] }. Also all, none, answered: true|false, and gte/lte for numbers. An array means all of them.

• You decide counts as picking the recommendation.

• A question in a hidden section is hidden, and picks in hidden questions don't count, so whole branches fold away. Their answers are kept (and reported as "now hidden") in case the branch comes back.

The page lists hidden questions under Hidden, with what would show each one.

Rich content

content (on the set, a section, a question or an option) is a markdown string, or a list of blocks:

Any block can have a title, and "collapsed": true to start closed.

Answers

Answers are saved in .questionme/answers/<set>.json, with a readable copy in <set>.md next to it. Each answer keeps the picked option ids and their labels, any "Other", text or number, your note, when, and a fingerprint of the question it answered. If the agent rewords the question later, the answer is flagged changed on the page (keep it or change it) and in get_answers.

The page

• List (every question, grouped) or Cards (one at a time, swipe or use the arrow keys, and it moves on after a pick).

• Filters: to answer, blocking, changed, later, answered, all, hidden. A filter stays put while you answer, so the card you just answered doesn't jump away.

• Search across questions and options.

• Take the recommendations for a section, or the whole set, then change the few you disagree with.

• Colour per section, numbered questions, a progress ring and bar, and a small celebration when you finish.

• Live: the agent's new questions, replies and "applied" notes appear as they happen, and so do answers from your other devices.

• Light and dark, a link to any question, and a prompt you can copy for the agent.

One server for every project, or one folder

npx questionme starts one shared server (the hub) for every project you've used it in. Your phone needs one bookmark. The MCP server starts the hub in the background when an agent needs a link, and adds the project to its list.

npx questionme                 # the hub (adds this folder); prints the links
npx questionme url [set]       # the links (starts the hub if needed)
npx questionme stop            # stop the hub
npx questionme projects        # what it serves;  --forget <folder> to drop one
npx questionme --solo [folder] # just this folder, on its own server

questionme --help prints every command and option, and a mistyped option is refused rather than ignored. Agents are told (in the MCP server's instructions and the CLAUDE.md section init writes) to check --help instead of guessing.

Your settings can also go in ~/.config/questionme/config.json (port, host, base, token (or false), allowHosts, notify). QUESTIONME_HOME moves that folder. It also holds projects.json (the hub's list), hub.json (where it's running), token, and hub.log.

The links include every address your phone might use: your Wi-Fi or LAN address, and a Tailscale address if you have one. Virtual adapters (WSL, Docker, VMs) are left out.

Under a path

--base team/questions (or QUESTIONME_BASE, or "base" in the config) serves everything under /team/questions/: the page, its scripts, project files, answers, live updates and the API. Any depth works, and team/questions, /team/questions, /team/questions/ and a full https://host/team/questions mean the same. The token cookie is kept to that path, /team/questions redirects to /team/questions/, and nothing is served outside it. The hub remembers its base, so the links it prints, the MCP server's get_link and notifications all include it. Point your proxy at questionme without stripping the path. To change the base of a running hub, questionme stop and start it again.

In Git Bash on Windows, leave off the leading slash: Git Bash rewrites /team/questions into C:/Program Files/Git/team/questions before questionme sees it (questionme refuses that, and says why). MSYS_NO_PATHCONV=1 turns the rewriting off.

Notifications on your phone

The hub can buzz your phone when an agent adds questions or replies on a thread. Tapping the notification opens the set.

npx questionme notify ntfy             # makes a private ntfy topic, saves it, and sends a test
npx questionme notify webhook <url>    # or POST JSON anywhere: Pushover, Discord, Home Assistant, …
npx questionme notify link http://100.100.4.74:4195   # where the tap should open (default: Tailscale, else your LAN)
npx questionme notify test | off       # send a test, or stop

For ntfy, install the ntfy app (Android or iOS) and subscribe to the topic it prints. Changes are batched: an agent adding 50 questions over a minute sends one notification ("Weather app: 50 new questions, 3 blocking"), once it has been quiet for 20 seconds (quietSeconds in the config) or two minutes have passed. Notifications name the set and quote the first new question, never your answers. Links leave out the token unless you set includeToken: open questionme once on your phone and its cookie does the rest.

The webhook gets { title, message, url, project, set, newQuestions, blocking, replies }.

Why not Web Push: a phone only allows it on HTTPS pages, and questionme is opened over plain http on your network.

Safety

• A token by default. The server listens on your network so your phone can reach it, so every request needs the token: in the link once, then a cookie. --local listens on this computer only.

• Project files shown in questions come only from inside that project, never .git or secret-looking files (.env, *.key, *.pem, id_rsa), and never through a link that points outside.

• What an agent writes is treated as untrusted: markdown is sanitised, HTML mockups run in a sandbox with no scripts, SVGs and files are served so they can't run script, and diagrams are drawn as images.

• DNS rebinding is refused (unknown host names), and so are writes from other sites.

• It only writes in .questionme/answers/ (the page and the CLI), .questionme/sets/ (the MCP tools and the CLI), and its own config folder. init also writes CLAUDE.md and, with --hook, .claude/settings.json.

The API

Development

npm install
npm test                 # builds, then runs the tests
npm run dev -- --solo .questionme-test/demo --local   # after: node scripts/demo.mjs .questionme-test/demo
npm run screenshots      # the README's screenshots, from the demo project

Releasing: bump the version in package.json (npm version patch --no-git-tag-version), commit, push to main. The Release workflow sees a version that isn't on npm yet, runs the tests, publishes it with trusted publishing, then tags the commit v<version> and makes a GitHub release.

License

MIT