alloverart

AskHooman server

Community alloverart
Updated

AskHooman: asks and tasks between people and their AI agents. An MCP server + app API, data in each user's own Google Drive

AskHooman server

AskHooman lets people keep track of asks and tasks between themselves and their AI agents. An agent that needs a decision puts an ask on its human's list instead of asking in a chat; the human answers with one tap, and the agent picks the answer up the next time it checks. Agents also record their own long-running work as tasks, so they don't forget it and the human sees who is doing what.

This repository is the server: a hosted MCP server for agents plus an app API for the AskHooman apps. The data of record lives in each user's own Google Drive, in the hidden per-app appDataFolder; the server keeps only accounts, connected agents and tokens (in Firestore).

  • Agents connect with one URL (https://<host>/mcp) using MCP authorization (OAuth 2.1 with PKCE, client ID metadata documents or dynamic client registration), signing the user in with Google. Clients without OAuth can use an agent key created in the app.
  • The official instance runs at https://askhooman.com (until 01.11.2026 the product was called Qtracker; https://qtracker.allover.art is still served as an alias, so agents connected there keep working).
  • The AskHooman iOS/macOS app is a separate, proprietary client and is not part of this repository.

Self-hosting

The server runs on Google Cloud Run with Firestore; the step-by-step guide is deploy/hosted/README.md. A self-hosted server needs its own Google Cloud project, its own Google OAuth clients and its own app/clients: Drive's appDataFolder is scoped to one Google Cloud project, so data written through your project is invisible to apps registered in another project (including the official AskHooman apps), and the reverse.

The contract (fields, statuses, REST, MCP, Drive file format, OAuth details) is SPEC.md. Contributions are welcome: see CONTRIBUTING.md. Security reports: SECURITY.md. License: Apache-2.0. The license does not grant rights to the AskHooman name and logo (server/hosted/static/); a public instance of your own should use its own name and icons.

Concepts

Asks: open (waits for the human) → answered (the agent acts on the answer) → closed. The agent closes its ask with a one-line resolution of what was done; the human can also close an open ask as not relevant, and either can reopen it. The full history, including earlier answers, stays in the ask's events.

Tasks: active (the agent is working on it) ⇄ waiting (blocked on someone outside; waiting_on says who, next_check when to look again) → done or dropped, with a one-line result. Only the agent that owns a task writes it; the human only reads tasks. Anything that needs the human's decision is an ask, not a task.

MCP tools: ask_create, asks_mine, asks_list, ask_get, ask_update, ask_close, and task_create, tasks_mine, tasks_list, task_get, task_update, task_done, task_drop, task_reopen; on the hosted bridge also set_my_look (the agent's own colour and icon in the app), ask_wait, set_my_webhook and test_my_webhook (below), and ask_attach, ask_upload and ask_detach for pictures and video in asks (ask_create takes attachments there too: PNG, JPEG, WebP or MP4 by URL, inline or uploaded from the agent's disk, or a link card; stored in the user's Drive next to the ask). The server instructions tell agents to call asks_mine and tasks_mine at the start of every session and when woken.

Waking the agent (hosted): when the user answers, closes or reopens an ask or replies on a task, the app tells the bridge, and the bridge puts a short event (type and ids) into the owner agent's feed and calls its webhook if it has one. The agent's side reads the feed over a connection it opens itself, so no public URL is needed: the Claude Code channel plugin in plugins/claude-code (see its README), MCP ask_wait, askhooman listen --exec (the CLI below) or GET /api/agent/events?after=<cursor>&wait=50 directly. Agents with a server wire their own webhook with set_my_webhook. The user can turn waking off per agent in the app.

House rules for agents

AskHooman only works if the list in your human's app is true. A question already answered in chat, or a task that finished last week, teaches them to stop looking.

  1. Check in first. At the start of every session and whenever you are woken, call asks_mine and tasks_mine before anything else.
  2. Act on every answer, not only the newest: do what your human said, then ask_close with one line of what you did. Nothing answered stays open past your session.
  3. Answered elsewhere? Close it here. If your human answers in a chat, by email or out loud, or the question stops mattering, ask_close it yourself and say where the answer came from. Never make them answer twice.
  4. Decisions go in asks, not in chat. One decision per ask, likely answers as options; keep working on what doesn't depend on it. The question changed? ask_update it instead of opening a second one.
  5. Keep your tasks true. Work that takes more than a day or waits on someone outside is a task. When anything moves, task_update it (status, waiting_on, next_check); an overdue next_check means look now. Finished: task_done or task_drop with a one-line result.
  6. A task with reply_pending waits for you: act on your human's reply, then task_answer it (or update or finish the task).
  7. Wake up when they answer. In Claude Code, suggest the AskHooman plugin to your human (one install, no server). Elsewhere, call ask_wait while you wait for an answer. If you can receive an HTTPS POST, ask your human (with ask_create) whether to set up set_my_webhook, and check it with test_my_webhook.

The same rules are on the site at /agents (https://askhooman.com/agents for the official instance), linked from the landing page and /llms.txt; the server instructions carry the short version.

Layout

server/              FastAPI app: REST /api, MCP /mcp (uvicorn server.app:app)
server/hosted/       hosted multi-tenant mode: OAuth server, agents and tokens, Drive records, app API, webhooks
server/tests/        pytest suite, no network (fake Google, Drive and Firestore)
cli/asks.py          stdlib-only CLI for the REST API (and `listen` on the hosted bridge's event feed)
plugins/claude-code/ the AskHooman channel plugin for Claude Code (marketplace: .claude-plugin/marketplace.json)
deploy/hosted/       Dockerfile, Cloud Build config and the Cloud Run guide

Two modes

Hosted (ASKS_MODE=hosted): many users, each signs in with Google; asks and tasks are read and written directly in the user's Drive appDataFolder, with the same validation and state machines as the single-tenant mode (server/rules.py, server/task_rules.py). This is what the Cloud Run guide deploys.

Single-tenant bridge (default, no ASKS_MODE): one human and their agents, data in a local SQLite file, static bearer tokens. Optionally it posts Telegram notifications when the human answers, and mirrors everything into one Google account's Drive appDataFolder. It is meant for a private network; it has no OAuth.

Single-tenant bridge

Run

Dependencies only through uv:

mkdir -p _tmp/dev
python3 - <<'EOF'
import json, secrets
tokens = {secrets.token_urlsafe(24): {"role": "denis"},  # the human (legacy role id, see SPEC.md)
          secrets.token_urlsafe(24): {"role": "agent", "agent": "research-bot"}}
open("_tmp/dev/tokens.json", "w").write(json.dumps(tokens, indent=2))
EOF
chmod 600 _tmp/dev/tokens.json
ASKS_DB=_tmp/dev/asks.db ASKS_TOKENS=_tmp/dev/tokens.json \
  uv run --python 3.11 --with-requirements server/requirements.txt \
  python -m uvicorn server.app:app --host 127.0.0.1 --port 8790

Tokens file (ASKS_TOKENS): {"<token>": {"role": "denis"}, "<token>": {"role": "agent", "agent": "<slug>"}}; tokens are at least 16 characters, slugs are lower-case [a-z0-9_-]. The role id denis means "the human" (a legacy identifier that is also written into the data files). The server re-reads the file when it changes, so adding or revoking a token needs no restart; if an edited file stops parsing, the server stops accepting all tokens after 5 seconds (and logs an error) until it is fixed, so a revoked token can't survive a stray comma. Every agent gets its own token: the server takes the identity from the token, so one agent can't act as another.

Environment (see server/config.py):

variable meaning
ASKS_DB SQLite file (default data/asks.db)
ASKS_TOKENS tokens file; without it every request gets 401
ASKS_WEB_DIR optional static web client served at / (default web/, not included in this repository)
ASKS_NOTIFY 1 enables Telegram notifications (default off)
ASKS_TG_TOKEN_FILE file with the bot token that posts them
ASKS_TG_CHAT chat id to post to (no default)
ASKS_TG_HANDLES JSON {"<agent slug>": "@bot_handle"}: the handle each message starts with, so that agent's bot wakes up
ASKS_TG_AGENT_CHATS JSON {"<agent slug>": "<chat id>"}: per-agent chat overrides
ASKS_DRIVE, ASKS_DRIVE_CLIENT, ASKS_DRIVE_TOKEN, ASKS_DRIVE_POLL Drive mirror, see below

When the human answers, closes or reopens an ask, the notification goes to the chat with the agent's handle in front ("@bot Your ask #12 «…» was answered: …"); agents' own actions never notify. @ in agent-written titles is defused, so only the leading handle mentions a bot. Failed sends are retried after 5 s, 30 s and 2 min (429 waits as long as Telegram asks) and never fail the API call.

Back up the SQLite file with SQLite's online backup (e.g. sqlite3 asks.db ".backup asks-copy.db"): it is safe while the server runs.

Connect an agent

claude mcp add --scope user --transport http asks http://<server>:8790/mcp \
  --header "Authorization: Bearer $(cat ~/.config/asks/token)"
claude mcp list        # asks should be connected

Put --header after the URL, otherwise it swallows the name and URL as extra headers. Rules for agents (also in the tool descriptions): one decision per ask, with a title the human can answer in one tap and 2–5 lines of context; update an open ask instead of creating a duplicate; after acting on an answer, ask_close(id, "what was done").

CLI

alias asks='python3 cli/asks.py'
asks me
asks list --mine                       # my open + answered asks, with answers
asks list --status all --agent research-bot
asks show 12                           # context, options, links, answer, history
asks create --title "Ship X today?" --context "2–5 lines" --option "Yes" --option "No" \
            --link "Plan|https://example.com/plan" --ref "chat 5487"
asks update 12 --option "Yes" --option "Later"   # replaces the whole list of options
asks close 12 --resolution "shipped X"
asks answer 12 --text "Yes"            # the human's token only
asks tasks --mine                      # my active + waiting tasks, nearest check first
asks task create --title "Get the supplier to confirm the new fabric" --status waiting \
                 --waiting-on "Supplier support reply" --next-check 2026-11-03
asks task done 3 --resolution "Supplier confirmed"
asks --json list                       # raw JSON

The server address comes from ASKS_URL (default http://127.0.0.1:8790), the token from ASKS_TOKEN or the file ASKS_TOKEN_FILE (default ~/.config/asks/token). On an HTTP error the CLI exits with code 1 and prints the server's detail. --context - and --text - read stdin; create --json FILE takes one object or a list.

With the hosted bridge (ASKS_URL=https://askhooman.com and an agent key from the app as the token), listen waits for the user's answers, closes, reopens and task replies and runs a command per event (ASKHOOMAN_EVENT, ASKHOOMAN_ASK_ID / ASKHOOMAN_TASK_ID in its environment); it starts now, retries after network errors from where it was, and stops on 401:

alias askhooman='python3 cli/asks.py'
askhooman listen --exec 'claude -p "check asks_mine and tasks_mine"'

Drive mirror

With ASKS_DRIVE=1 the bridge writes every ask and task into the appDataFolder of one linked Google account (ask-<id>.json, task-<id>.json) and every 15 s (ASKS_DRIVE_POLL) replays the human's answers, closes and reopens made by an app directly in those files. The format and rules are in SPEC.md, "Drive storage". It needs a Desktop app OAuth client of your Google Cloud project (ASKS_DRIVE_CLIENT: its JSON as the console downloads it, or flat {"client_id", "client_secret"}) and a refresh token for the https://www.googleapis.com/auth/drive.appdata scope obtained with the installed-app loopback flow (ASKS_DRIVE_TOKEN: {"refresh_token": "..."}, chmod 600). If Google is unreachable or the token is revoked, the API keeps working from SQLite, a warning is logged (never the token) and the mirror catches up later; a new token file is picked up without a restart. Nothing is ever deleted from Drive.

Development

uv run --python 3.12 --with-requirements server/requirements.txt --with-requirements deploy/hosted/requirements.txt \
  --with httpx --with pytest python -m pytest server/tests -q

The tests need no network and no Google Cloud: Google, Drive and Firestore are faked in memory, and the hosted tests include an end-to-end run of the official MCP client with its OAuth flow. CI runs the same command on every pull request.

MCP Server · Populars

MCP Server · New

    kitfunso

    Hippo

    One memory for every agent you'll ever use. Hippo writes what you teach a coding agent into a store in your repo, and your other agents read that same store.

    Community kitfunso
    Avazbek22

    DevProjex: MCP / GUI / CLI / TUI all in one

    Repomix alternative with up to 40% fewer tokens. Turn any codebase or Git repository into safe, token-efficient context for LLM and coding agents like Claude Code, Codex, and Cursor. GUI, TUI, CLI, and a read-only RAG MCP server with Live Context, agent journal, Smart Ignore, secret/PII redaction, and code compression. Windows, macOS, Linux.

    Community Avazbek22
    membaseai

    Membase

    Memory layer for AI agents — SDKs, CLI and MCP server for Membase

    Community membaseai
    dosco

    DeepORG — One AI Agent for Your Whole Organization

    DeepORG (formerly GraphJin) — one AI agent for your whole organization: databases, APIs, files, and code over MCP

    Community dosco
    scumble-app

    Scumble

    Free, open-source desktop editor for AI inpainting: select, prompt, get a colour-matched layer. FLUX 3 Image, FLUX.2, GPT Image, Nano Banana, Seedream and Qwen through your API key or your own ComfyUI. Layers, PSD export, MCP.

    Community scumble-app