A private pager for your agent loops.
Website  . Phone app  . npm  . Repo  . For agents  . Security
You run a hundred agents in loops, full permissions, mostly while you are asleep or away from the keyboard. They are not supposed to need you. Then, every so often, one of them hits the single step it should not take alone, and it has no way to reach you.
So reach back. ask-a-human lets that one agent tap you on the shoulder: it pings your phone and blocks until you answer, then unblocks and rolls on. Seconds, not minutes.
For years, CAPTCHAs made humans prove they are not robots. Now you register yourself as a tool your agents call.
100 agents. One human. One buzz at a time.
Use agent 0.2.1 with the current phone app. Download and verify the signed GitHub release binary, then keep its full path for the configuration below. This works while npm publication is unavailable; use an exact compatible version rather than an older or unpinned npm package. ask-a-human needs no account or API key.
Register the local server with the Codex CLI, replacing the example path with your verified binary:
codex mcp add ask-a-human -- "/absolute/path/to/ask-a-human" serveThen edit the resulting entry in ~/.codex/config.toml to allow time for a phone response. You can also add this table directly, without running the command above:
[mcp_servers.ask-a-human]
command = "/absolute/path/to/ask-a-human"
args = ["serve"]
tool_timeout_sec = 600600 allows ten minutes for a tool call; increase it if you need longer. Codex's default is 60 seconds, and a request's expires_in_s can end the wait sooner. The Codex CLI and desktop/IDE clients on the same host share this configuration. See the official Codex MCP documentation.
Restart your Codex session, then use codex mcp list or /mcp in the terminal UI to check the server. Ask Codex to call start_pairing, then follow the phone steps below.
For Cursor (~/.cursor/mcp.json) or Claude Desktop (claude_desktop_config.json), use their JSON configuration and restart the client:
{
"mcpServers": {
"ask-a-human": {
"command": "/absolute/path/to/ask-a-human",
"args": ["serve"]
}
}
}- The local server defaults to the hosted relay
wss://ask-a-human.ai/wsand the PWA athttps://ask-a-human.ai. start_pairing(or the firstrequest_approval) prints the pairing code to stderr and opens a local loopback browser page showing it. The code is never in a URL.- Pin
https://ask-a-human.ai/appto your iPhone home screen as a PWA, then type the code. (On iOS, Web Push only works once the app is installed to the home screen, and wake-ups are best-effort; when you open the app it shows a pending-count badge.)
Running your own relay? Point the agent at it with --relay <wss-url> (and --public-relay <wss-url> if your phone reaches the relay at a different address). See self-hosting.
The hosted app at ask-a-human.ai connects only to its hosted relay. For a custom relay, open your self-hosted PWA and set its relay URL in Advanced. If the relay uses a different origin from that PWA, allow that specific origin in your server's connect-src CSP. Local development continues to accept loopback relay URLs.
Upgrading from 0.1.x? Version 0.2.1 requires an updated agent and phone app, followed by fresh pairing. See the upgrade and iPhone test guide.
Claude Code |
Codex |
Cursor |
Copilot |
Gemini |
Any MCP client |
If it speaks MCP, it can reach you. Configure ask-a-human as a local stdio MCP server in your client.
Four things, and that is the whole product. You pair once, then every request_approval blocks the agent until you answer.
It NEVER auto-approves. A decline, a timeout, or an error is never returned as approved. Silence is not a yes.
This is how a hundred agents become one buzz at a time. Pair each agent once and it gets its own chip in a roster strip, labeled by --name (say cursor @ workstation or nightly-deploy-bot) so you always know who is asking. When an agent needs you, its chip lights up with a pulsing red dot and jumps to the front of the strip. Tap it, answer, move on. Pair as many as you want.
1. Agent hits a wall it should not pass alone
2. The request is sealed in a wormhole
3. Your phone buzzes
4. You tap: approve, decline, or reply
5. The agent unblocks and rolls on
Seconds, not minutes.
We built this for ourselves first. The hard part of running agents in bulk was never the work, it was the rare moment one of them needed a judgment call and we weren't at the keyboard.
We didn't want a dashboard, an account, or another company holding our messages. So it's private by design: everything travels through a magic wormhole, end-to-end encrypted, and the relay in the middle is blind. We don't track anything, there's no database, and we pay for the hosting ourselves.
No data to sell, no funnel, no catch. We built it because we needed it, and our only goal is for it to spread.
The MCP server runs locally on your machine. It and your phone hold the keys and plaintext. The hosted relay forwards encrypted traffic between them.
AGENT SIDE RELAY (content-blind) YOUR PHONE
+--------------+ seal +------------------+ blob +----------------+
| MCP agent | ----------> | rooms-of-two WS | -------> | phone PWA |
| request_ | | verbatim forward | | swipe / choose |
| approval | <---------- | RAM-only, no DB | <------- | / reply -> seal|
+--------------+ open +------------------+ blob +----------------+
the relay sees only ciphertext + which room-id talks to which
Three tools. No surprises.
Ask a human. BLOCKS until they respond. Pass expires_in_s to also time out after N seconds; omit it and the call waits indefinitely (until answered, or the connection drops).
| Field | Type | Required | Notes |
|---|---|---|---|
title |
string | yes | Short card title. |
summary |
string | yes | The question body. |
response_kind |
string | yes | "yesno" | "choice" | "text". |
category |
string | no | Badge. Recognized: cash | deploy | data | access | other. Any other value is still shown, just with the neutral other color. |
options |
string[] | no | Choices when response_kind is "choice". |
placeholder |
string | no | Input hint when "text". |
max_len |
integer | no | Text limit in Unicode scalar values, 1–4096; omitted or 0 defaults to 4096. |
expires_in_s |
integer | no | Lifetime in seconds, 1–86400; omitted or 0 has no request-owned timeout. Caller cancellation/deadline still applies. |
Returns the shape you asked for: yesno gives an approved boolean, choice gives the selected option, text gives the typed reply. A decline comes back as a non-approval; a timeout or transport error is returned as an error the agent can branch on. It never silently proceeds, and never returns approved on failure.
Requests are validated before pairing: IDs up to 256 Unicode scalar values, titles 512, summaries 4096, agent/category/input hints 256, and 1–32 unique nonempty choice options up to 256 each. Only fields for the selected response kind are accepted. Encoded messages, including JSON escaping and signatures, are limited to 16 KiB. Text is preserved exactly, including whitespace and explicit {"text":""} empty replies.
Protocol v2 authenticates both peers' signing identities during pairing and signs the full question, answer, and agent receipt. The phone shows Answer received by agent only after verifying that receipt; a sent answer with no receipt remains uncertain. This confirms acceptance of the answer, not execution of an external action. The absolute deadline survives reconnects and page reloads. Authenticated request and subscription sequences prevent recorded older messages from replacing newer observed state; atomic IndexedDB counters preserve this across tabs and reloads. Missing sequence storage requires explicit re-pairing.
After upgrading from an older protocol, update the agent, refresh the phone app, and call start_pairing with {"reset":true}. Saved older entries remain visible with repair instructions; unsigned compatibility is disabled. The phone needs working WebCrypto and IndexedDB for secure signing.
Read-only. Reports whether a pairing session exists and whether the relay currently reports the phone present, or whether pairing is waiting/idle. Never returns the code or changes the session. Does not start pairing (use start_pairing for that).
Begins pairing with your phone eagerly, instead of waiting for the first request_approval. Prints the short code in the agent terminal for you to type into the app; the handshake runs in the background. Returns only non-secret status. The code never appears in the result. An ordinary call preserves an existing session and joins an attempt already in progress.
If you removed the agent entry from the phone or the phone forgot its pairing, call start_pairing with {"reset":true} and enter the fresh code. This explicitly disconnects the old session and discards its session key, device-key pin, and push subscription before pairing again. Reset refuses while an approval is pending; answer or cancel that request first. Reopening the app after an ordinary disconnect does not require a reset. A failed pairing releases all waiting callers with the failure, and the next call can start a fresh attempt.
For agents: https://ask-a-human.ai/llms.txt
This is the whole point, so it is built to be boring and verifiable.
- End-to-end encrypted. Plaintext only ever exists on your machine and on your phone.
- Content-blind relay. It only ever forwards
base64(nonce‖ciphertext)plus which room talks to which. It can record, delay, replay, or drop traffic. Signed request digests and per-pair sequence checks prevent it from forging a decision or rolling observed authorization state backward. - No accounts or relay database. The local agent retains pairing secrets in memory; restarting that agent requires re-pairing. The phone persists its pairing in browser storage. A relay restart disconnects the peers, which can reconnect using their existing pairing. See
SECURITY.mdfor endpoint and storage risks. - Pairing is a SPAKE2-style PAKE. A short code becomes a strong shared key. A failed confirmation ends the pairing attempt, limiting online password guesses. Keep the code private: someone who learns the complete code can race the intended phone during pairing.
- App traffic is sealed with NaCl secretbox (XSalsa20-Poly1305), keyed by the symmetric SPAKE2 session key.
The PAKE is an in-house construction following RFC 9382 over the ristretto255 group (RFC 9496), Magic-Wormhole-inspired. Go uses gtank/ristretto255, the PWA uses @noble/curves, and Go to JS interop is pinned by frontend/test/spake2-interop.mjs. The short code is the PAKE password: it never reaches the model and never travels in a URL.
Read every line. See SECURITY.md and the ADRs in docs/decisions/architecture/ (start with 0002_spake2_ristretto255_secretbox.md for the crypto and 0011_npx_distribution_stdio_local_mcp.md for npx/stdio).
The server is already local. To point at your own relay, pass --relay:
"/absolute/path/to/ask-a-human" serve --relay <wss-url>If your phone dials the relay at a different URL than the agent does, add --public-relay:
"/absolute/path/to/ask-a-human" serve --relay <wss-url> --public-relay <wss-url>Or in a client that uses JSON configuration (for Codex, add the same flags to args in the TOML table above):
{
"mcpServers": {
"ask-a-human": {
"command": "/absolute/path/to/ask-a-human",
"args": ["serve", "--relay", "wss://your-relay/ws"]
}
}
}The serve flags are --relay <wss-url> (the relay the agent dials), --public-relay <wss-url> (the relay the phone dials, when it differs from --relay), and --name <text> (who is asking, shown on the card). The MCP server still runs locally (it has to: it holds the key and the plaintext). Only the content-blind relay and the static PWA move to your infra. Both are in this repo, MIT-licensed, with deploy manifests under infra/.
Mirroring the binary. The postinstall verifies the downloaded binary's sha256 before installing it, so a custom AAH_BINARY_BASEURL mirror must serve checksums.txt over https alongside the archives, or you must pin the digest out of band with AAH_BINARY_SHA256=<sha256>. Plain http:// mirrors are rejected. To place the binary yourself, set AAH_SKIP_DOWNLOAD=1 and drop it in node_modules/@askahuman/mcp/bin/.
| Path | What's inside |
|---|---|
backend/ |
Go relay (cmd/relay) + MCP agent (cmd/agent); pkg/spake2, pkg/sealedbox, pkg/wire. |
frontend/ |
Astro 5 + React 19 + Tailwind 4 static PWA (the app and the landing); client-side crypto. |
npm/ |
@askahuman/mcp wrapper: postinstall pulls the matching release binary; bin/cli.js execs it. |
infra/ |
ctlptl/kind cluster, ko/Tilt build, kustomize base/local/prod (GKE). |
docs/ |
plan.md + decisions/ (ADRs). Read these first. |
Local dev runs on Tilt + kind (make up / make ci-up).
| What | Command |
|---|---|
| Backend unit tests | make backend-test (go test ./...) |
| Backend integration | go test -tags integration ./... (in backend/) |
| Frontend unit tests | bun run test (in frontend/) |
| SPAKE2 interop | node test/spake2-interop.mjs (in frontend/) |
| End-to-end | make ci-up && make e2e (live agent + relay-in-kind + real PWA in headless Chromium) |
More depth lives in docs/ (start with plan.md and the ADRs).
- Repo: https://github.com/askahuman/askahuman
- Website: https://ask-a-human.ai
- App (phone PWA): https://ask-a-human.ai/app
- npm: https://www.npmjs.com/package/@askahuman/mcp
- For agents: https://ask-a-human.ai/llms.txt
- Found something? See
SECURITY.md. - Licensed under MIT. Read every line, run your own, make it yours.
100 agents. One human. One buzz at a time.