ADHD Progress Hub
This MCP server is a self-hosted progress hub for tracking coding work, projects, threads, checkpoints, and reminders.
Manage projects: list, resolve, register workspaces, upsert metadata, and queue rename/delete for human confirmation.
Manage work threads: list open threads, create/update threads, save progress checkpoints, pause with a resume step, mark done, dismiss, and triage stale threads.
Resume work: build session digests, get a compact overview, check overlap before starting tasks, and get calm next-up suggestions.
Handle reminders: list due/history reminders and create once, session, daily, or random reminders.
Support agent integrations: report local guidance-health versions and push compact Hub digests into OpenClaw memory.
Filter by project or energy, use read-only inspection tools, and rely on human confirmation for destructive project actions.
Provides forge sync capabilities for Gitea: pushes wiki/progress files, mirrors threads as labeled issues, optionally attaches them to project boards, imports existing progress files, and polls cloud-agent issues to create threads.
Provides forge sync capabilities for GitHub: pushes wiki/progress files, mirrors threads as labeled issues, optionally attaches them to project boards, imports existing progress files, and polls cloud-agent issues to create threads.
ADHD Progress Hub
Self-hosted source of truth for half-finished plans, migrations, and setups — so coding agents (Cursor, Codex, Claude Code, …) can check overlap, save progress, and nudge you later.
Inspired by claude-adhd (see ATTRIBUTION.md). This project is tool-agnostic: MCP over Streamable HTTP (plus an optional local stdio transport) + REST, optional OpenClaw notifications, and an optional local transcript indexer (summaries only).
Screenshots
My work with Notes & context (projects list, calm rows, and the reader opened beside them):

Now | My work | Progress | Settings |
|
|
|
|
Gallery shots use dummy demo data (Now shows a saved “Where you left off” step and a gentle “Is this still on your list?” check). More UI detail: Dashboard · Notes & context.
Related MCP server: Seamless
Why
You start a Proxmox migration / homelab setup / refactor in Cursor Cloud, continue on a Dev LXC, forget for a week, then rediscover a half-finished chat — or you don’t. The hub keeps:
Threads — open / blocked / done / dismissed work items
Progress wiki —
data/wiki/projects/<slug>/PROGRESS.mdOverlap checks — “am I about to redo something half-done?”
Reminders — once / session / daily / random
OpenClaw bridge (optional) — chat nudges + memory sync when you’re away from the IDE
Quick start
Docker Compose with a published image is the recommended persistent server install. See the full installation guide for a ready-to-copy Compose file, docker run, source/uv, upgrades, backups, reverse proxies, and client-only CLI installs. Every server setting is documented in the environment variable reference. Hub state (SQLite including project tags and scan-line cache, plus ai.json AI settings) lives under /data in the container — mount a named volume or bind there and keep ADHD_HUB_DATA_DIR=/data (see What lives under /data).
Docker from this checkout
The repository Compose file builds the current checkout:
cp .env.example .env # set a real ADHD_HUB_AUTH_TOKEN
docker compose up -d --build
curl -fsS http://127.0.0.1:8787/api/healthFor a released server without a source checkout, use ghcr.io/uniskela/adhd-hub:latest (or a pinned X.Y.Z) as shown in the installation guide.
Run from source with uv
cp .env.example .env # set ADHD_HUB_AUTH_TOKEN
uv sync
uv run adhd-hub serve --host 127.0.0.1 --port 8787Local MCP over stdio
For MCP clients that launch a local subprocess, the same Hub tool catalog can run over stdio:
adhd-hub mcp-stdioGeneric MCP config:
{
"mcpServers": {
"adhd-hub": {
"command": "adhd-hub",
"args": ["mcp-stdio"]
}
}
}Stdio is an optional local mode: it uses the configured Hub data directory and the same MCP tools, but it does not start the REST API, dashboard, or background scheduler. It has no bearer header because the MCP connection is the local child process itself. For a persistent/shared Hub, remote agents, OAuth, dashboard access, and scheduled reminders, keep using adhd-hub serve/Docker and the Streamable HTTP /mcp endpoint.
See the MCP tool contract for parameter metadata, output compatibility, side effects and local regression checks.
Published images (only after a manual release-PR merge by uniskela):
:latest,X.Y.Z, andX.Yon the Git tag created for that release (for example0.22.1,0.22)
Releases (Release Please): after uniskela manually merges a PR to main with Conventional Commits (feat:, fix:, feat!:…), Release Please opens or updates a release PR. It never auto-merges that PR. When uniskela manually merges the release PR, Release Please creates vX.Y.Z and then publishes the matching multi-architecture images. The publish workflow has no direct push, PR, or manual trigger. Squash merges use the PR title as the subject (body bullets do not count); keep titles conventional for release-surface work — see AGENTS.md / CONTRIBUTING.md.
Pre-1.0 bumps (see release-please-config.json): fix: → patch, feat: → minor, feat!: / breaking → minor (not 1.0.0 yet).
Documentation, chore, test, and CI-only merges do not open a release PR, even if their subject accidentally starts with feat:. A feature, fix, performance, revert, or explicit breaking-change subject reaches Release Please only when that commit changes a shipped runtime surface (src/, package metadata/lockfile, Dockerfile, or docker-compose.yml). A generated release PR continues through the tag-and-publish step after uniskela manually merges it.
docker pull ghcr.io/uniskela/adhd-hub:latest
docker pull ghcr.io/uniskela/adhd-hub:0.22.1Repo secrets for Docker Hub: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN. GHCR uses GITHUB_TOKEN (packages: write). After a successful image publish, the same Hub secrets push this README (Hub truncates at 25k bytes) and the GitHub repository short description onto uniskela/adhd-hub (DOCKERHUB_TOKEN must be a Hub PAT with Read, Write, and Delete).
Connect Cursor
Marketplace plugin (recommended for Cursor): install adhd-hub-cursorskill (Marketplace once published, or local/dev install of that repo). With a Hub already running, set plugin variables ADHD_HUB_MCP_URL ({base}/mcp) and ADHD_HUB_AUTH_TOKEN, then verify MCP tools and skills. That plugin ships the Hub rule + session/projects/env-check skills with Marketplace wiring; Hub remains the skill source of truth (Cursor plugin skill sync).
Project / CLI connect (monorepos, adhd-hub connect, or non-Marketplace setups): merge adapters/cursor-mcp.json into your MCP config (URL + bearer via ${env:ADHD_HUB_AUTH_TOKEN}), install the rule from adapters/cursor-rule.mdc into .cursor/rules/, and optionally install skills:
# Install from the published repository:
npx skills add uniskela/adhd-hub -g
# Or, while developing an unreleased local checkout:
npx skills add ./skills -gOr use adhd-hub connect … --agents cursor --cursor-rule --skills — see docs/public/connect.md.
Optional third-party companions (i-have-adhd, Superpowers, Ponytail, Graphify, Context7, agent-browser, RTK, Serena, Humanizer): see docs/public/coding-companions.md. Choose only the tools that fit your workflow; Hub Settings → Coding agents and adhd-hub connect --with-* provide the supported opt-in install paths.
For calm, resumable project notes and plans, use the ADHD-friendly writing guide: one visible Now action, brief context, and a concrete return cue.
Documentation site: uniskela.com/docs/adhd-hub (Zensical via uniskela/com). A GitHub Pages mirror stays at uniskela.github.io/adhd-hub until the Pages cutover. Preview locally with uv sync --extra dev && uv run zensical serve. The Pages workflow deploys only from main after uniskela merges documentation changes; it does not run for pull requests or manual dispatches.
MCP (recommended persistent/shared transport):
http://<host>:8787/mcpMCP (optional local subprocess transport):
adhd-hub mcp-stdioREST docs:
http://<host>:8787/docsUI:
http://<host>:8787/ui/
MCP tools
Tool | Purpose |
| Compact open threads (goal/focus/next/resume) + reminders |
| Rank open threads vs what you’re starting (goal/title/focus) |
| Review same-outcome evidence and safe merge eligibility |
| Queue a local duplicate merge for explicit human confirmation |
| Read retained source threads, notes and events under their original IDs |
| Map workspace path → project slug |
| Project registry (+ optional forge overrides) |
| Queue rename/delete for /ui confirmation (not applied immediately) |
| See delete/rename requests waiting for you |
| List unfinished work |
| Create/update a thread (one finishable outcome) |
| Update thread state + PROGRESS.md ( |
| Leave a concrete resume step |
| Close a known thread |
| once / session / daily / random |
Using this project with AI coding agents
If you use Codex, Cursor, Claude Code, or another assistant with Context7 MCP, you can ask it to consult the project's documentation before setting up or integrating the Hub. Context7 is optional and separate from ADHD Progress Hub's own MCP server.
Use Context7 MCP to resolve the official documentation library for
uniskela/adhd-hub(expected ID:/uniskela/adhd-hub), then retrieve guidance for installation, agent connections, MCP transports and tools, authentication, and troubleshooting. Match the guidance to my installed ADHD Progress Hub version. If the library is still indexing or doesn't cover that version, check the maintained documentation and linked source files instead.
Optional OpenClaw
Install the Hub skills for OpenClaw:
npx skills add uniskela/adhd-hub -g -a openclawPairing (recommended): In Settings → Phone alerts, click Start pairing, copy the prompt into OpenClaw, then Approve what it submits. OpenClaw never needs ADHD_HUB_AUTH_TOKEN — only the short pairing code. Full steps: OpenClaw connection and alerts.
Manual path: Enable private hooks on the OpenClaw gateway. Then in Settings → Phone alerts, save the webhook or agent URL, bearer token, alert schedule, stale age, cooldown, and alert size. Use Save and send a test to verify the route.
The bearer token is encrypted before it is written to the Hub data directory and is never returned to the browser. Environment variables remain available for initial provisioning:
ADHD_HUB_OPENCLAW_WEBHOOK_URL=http://openclaw:18789/hooks/wake
ADHD_HUB_OPENCLAW_TOKEN=<OpenClaw hook bearer token>
# optional richer path:
# ADHD_HUB_OPENCLAW_AGENT_URL=http://openclaw:18789/hooks/agentEnvironment changes require a restart; web UI changes apply immediately. The stale-work job sends OpenClaw one concise, non-nagging reminder and stays quiet when there is no stale work. Keep both services on your LAN or Tailscale. See the OpenClaw guide for details.
Optional transcript indexer
On a machine that has local transcripts (does not upload raw chats — only heuristic summaries):
uv run adhd-hub index --dry-run
uv run adhd-hub indexRoots (override in config.toml [indexer]):
Cursor:
~/.cursor/projects/**/agent-transcripts/**/*.jsonlCodex:
~/.codex/sessions/**/*.jsonlClaude Code:
~/.claude/projects/**/*.jsonl
Homelab / Tailscale
See docs/public/deploy-homelab.md. Typical pattern: Docker on Proxmox LXC, publish :8787 on Tailscale, point Cursor Cloud + Windows + Dev LXC MCP clients at http://<tailscale-ip>:8787/mcp. When Cloud cannot join Tailscale, use a controlled HTTPS tunnel (Remote MCP access) or the forge mailbox — never anonymous /mcp.
Optional forge sync (GitHub / Gitea)
Open http://127.0.0.1:8787/ui/ after serve / compose. Project-first dashboard: pick a project, do Next up, Settings (token / timezone / forge) stays out of the way. Timezone defaults to your browser local zone on first visit (ADHD_HUB_TIMEZONE / data/prefs.json).
Wiki sync — pushes
INDEX.md+projects/<slug>/PROGRESS.md(primary memory: repo root; otherwise under Wiki path)Board sync — mirrors threads as Issues with labels
adhd-hub+project:<slug>; optionally attaches to a Gitea/GitHub project board idPrimary memory repo — seeds
README.md/AGENTS.md; leave Wiki path blank so files land atprojects/<slug>/(e.g.…/alex/projects/projects/adhd-hub)Import from forge — if the repo already has
projects/*/PROGRESS.md, Settings → Issue sync → Scan for projects (or after Sync) offers to register missing projects and pull progress files
Configure in Settings or via ADHD_HUB_FORGE_* env / data/forge.json. Rename/delete projects from the project panel (delete is safe by default — progress/forge files only removed if you opt in).
Note: Hub “wiki” = normal markdown files in the repo (INDEX.md, projects/*/PROGRESS.md). That is separate from Gitea/GitHub’s built-in Wiki feature. Issues show under the Issues tab when board sync works. Projects boards only if you set a project id/number.
Cloud / remote mailbox: enable Import cloud-agent issues (inbox) and set Inbox authors (fail closed: empty allowlist imports nothing). The Hub polls open issues from those usernames that either have the adhd-hub label or a title starting with [ADHD] (Cursor Cloud, Codex/ChatGPT, Claude, etc.), creates threads, then closes them with adhd-hub-synced (never deletes). Title prefix is enough when agents cannot set labels. Optional source:* labels record the tool. Agents should use a short Goal/Focus/Next/Resume body and may append a Made-with footer under ## Attribution. See docs/public/forge-issue-inbox.md.
PAT permissions: see docs/public/forge-permissions.md for GitHub (fine-grained + classic) and Gitea scopes.
Privacy
Default store: SQLite + markdown wiki under
data/Auth: REST and MCP accept bearer tokens.
/ui/supports a separate dashboard password, withADHD_HUB_AUTH_TOKENfor initial setup and recovery. Both issue a 12-hour HttpOnly, SameSite=Strict session cookie; credentials are never stored in localStorage. See password setup and recovery. Log out revokes the session. Browser sessions are stored in SQLite (data/browser_sessions.sqlite3) and survive a restart; login throttles stay in process memory. HTTPS sets the Secure cookie flag (configure trusted proxy headers when terminating TLS upstream).Default-token development mode is allowed only with a loopback bind. Set a long random token before binding to
0.0.0.0; generate one withpython -c "import secrets; print(secrets.token_urlsafe(32))". Use HTTPS for remote access.Cookie-authenticated writes require
X-Hub-Request: 1and a matching Origin when present. CLI and MCP clients continue using bearer auth.Settings precedence is process environment, then the first nonempty TOML file (
--config,./config.toml, or~/.config/adhd-hub/config.toml), then.env.ADHD_HUB_PUBLIC_URLsets the externally reachable Hub base URL used for browser/deep links, forge links, install/connect output, and MCP OAuth discovery.Bind
127.0.0.1for local-only, or Tailscale-only — do not expose publicly without a reverse proxy / tunnel terminator and strong token (Remote MCP access)Migrate instances with
/uibackup zip or forge Import (see docs/public/deploy-homelab.md). Optional passphrase backups use a versioned envelope: new exports are salted scrypt + Fernet (v2); v1 SHA-256 passphrase files still decrypt.
Adapters
Tool | Snippet |
Cursor | Marketplace: adhd-hub-cursorskill; project: adapters/cursor-mcp.json, adapters/cursor-rule.mdc |
Codex | |
Claude Code | |
OpenClaw |
Add Hub guidance to another project
Install a reversible, project-local AGENTS.md section that keeps coding-agent sessions connected to the Hub:
adhd-hub setup /path/to/projectAdd --install-skills to install Hub skills (session, projects, env-check) globally for every skills.sh agent, or pass --skills-source /path/to/adhd-hub/skills while developing locally. Skill installation is opt-in because it changes global skill directories. Use connect --skills --agents ... when you want selected agent targets. See project agent setup. Keep connected projects aligned with canonical Hub skills using project sync. For stronger Cursor enforcement than rules alone, opt into continuity guard with adhd-hub setup . --continuity-guard.
Connect (one-liner)
With the Hub running and ADHD_HUB_PUBLIC_URL set for remote clients, copy the command from Settings → Coding agents (no server token in the command):
# macOS / Linux / WSL / Git Bash
curl -fsSL http://<hub-host>:8787/install.sh | sh -s -- /path/to/project# Windows PowerShell
irm http://<hub-host>:8787/install.ps1 | iexThe CLI opens your browser (or prints a one-time code). Press Allow in the browser prompt, or type the code under Settings → Coding agents and choose Allow this computer. A session is saved on disk; do not export ADHD_HUB_AUTH_TOKEN into your profile for this step.
Install scripts prefer this Hub's /install/cli-wheel.url (a PEP 427 wheel matching the server), falling back to git+https. Choose agents in Settings → Coding agents (baked into /install.sh and /install.ps1), or pass --agents / ADHD_HUB_CONNECT_AGENTS. Hub alias claude maps to skills.sh claude-code; there is no Cursor-only default. Details: docs/public/connect.md.
adhd-hub doctor --hub http://<hub-host>:8787 --project /path/to/projectconnect and doctor print a scannable report: outcome banner and Hub URL, then Do next (success) or Fix these (failure). Color is on for a TTY unless NO_COLOR or ADHD_HUB_NO_COLOR is set. Layout: docs/public/connect.md.
adhd-hub connect merges MCP configs, writes the reversible AGENTS.md block, and can install Cursor rules, global skills, OpenClaw skills, register the project, and scan --find-roots.
To point an already-connected machine at a different Hub (for example localhost → HTTPS):
adhd-hub use-hub https://adhd-hub.example.com --project /path/to/project --agents cursor,codex,claudeRoadmap
The single public roadmap lives in docs/public/plans/improvement-roadmap.md. GitHub issue #15 is the canonical tracker when current status changes faster than the docs.
Current sequence:
Shipped — Foundation B3 #75 in v0.15.0 via #152: durable activity/event history, live UI invalidation, sync health and history.
Shipped — Wave 6 #52 in v0.16.0 via #159, #160, #161, and #162: heuristic and opt-in local LLM thread scan-lines, project tags, filters, last-touch cues, and organiser suggestions with confirm.
Shipped — Wave 7 #54 in v0.21.x: soft stale triage and calm Next-up ranking shipped in v0.18.0. Merge/dedupe suggestions with human-confirmed local merges (#312, #315) and advisory return-cue coaching (#317, #320) shipped in v0.21.0.
Also shipped in v0.21.x: opt-in Clock-Off wind-down #310, MCP schema quality #117 and locked CI installs #102.
Shipped — Wave 8 #55 in v0.22.x: progress compaction (#339), local search (#338), mobile capture (#341), and energy/context modes (#342) shipped in v0.22.x (#340).
Now — Activity insights #72: Slice A (ledger-backed totals, #345) and the 12-week completion calendar (#349, #352) shipped in v0.22.x (#340). Focus sessions and remaining metrics are next.
Later: shared/discovery surfaces #56.
Deferred/opt-in: Slack/Discord/calendar integrations #20.
Dashboard comfort
The dashboard includes light/dark/system themes, a focus view, quick task capture, and optional XP, levels, and daily goals. See dashboard preferences.
Development
uv sync --all-extras
uv run pytest
uv run ruff check src testsSee CONTRIBUTING.md.
License
MIT — LICENSE
Brand and rewards
See the brand guide for the logo, colours, and UI patterns. Current optional ranks, badges and shareable progress are documented in dashboard preferences; future public/competitive reward ideas are not part of the active roadmap.
Available Tools
27 toolscheck_overlapARead-onlyIdempotent
Find open threads that may overlap a planned task.
Use before starting potentially new work. The query should describe the intended task, and the result is read-only; compare likely matches before creating another thread.
Inputs: query (required), limit. Returns: object
confirm_thread_relevantADestructive
Confirm a stale open thread is still relevant (Wave 7 soft triage).
Quiets the “still relevant?” prompt via reminder cooldown. Does not
change status and never dismisses. Use snooze_thread_triage to ask again
later, or dismiss_thread only when the human intentionally abandons it.
Inputs: thread_id (required). Returns: object
delete_projectAIdempotent
Queue project deletion for human confirmation in /ui.
Nothing is deleted immediately. The flags describe what the confirmed
action should remove; use list_pending_actions to inspect the queued
request before confirmation.
Inputs: slug (required), reason, delete_remote, delete_progress. Returns: object
dismiss_threadADestructiveIdempotent
Soft-close a thread that should stop without being marked complete.
Use for abandoned, superseded, or no-longer-relevant work. Use mark_done
when the intended outcome was completed, or pause_thread when it will be
resumed later. Prefer confirm_thread_relevant / snooze_thread_triage for
a calm stale-work check — never auto-dismiss from those tools.
Inputs: thread_id (required), note. Returns: object
get_overviewARead-onlyIdempotent
Return a compact, read-only Hub overview for agents.
Includes counts, next-up work, and due reminders. Use session_digest when
you also need project-specific resume context or the progress wiki snippet.
next_up and triage_candidates carry advisory return_cue coaching.
clock_off reports the global opt-in schedule boundary and advisory guidance:
finish a small safe step, checkpoint with upsert_progress and pause_thread
instead of starting substantial new work. The user can override temporarily.
Inputs: no named parameters. Returns: object
list_open_threadsARead-onlyIdempotent
List unfinished threads without changing them.
Filter by project or energy when narrowing existing work. Use
session_digest when you want a session-start summary with reminders and
resume context instead of the raw thread list. Each thread carries
advisory return_cue coaching for its resume_step.
Inputs: limit, energy, project_slug. Returns: result
list_pending_actionsARead-onlyIdempotent
List project rename/delete requests waiting for /ui confirmation.
This is read-only and is useful after rename_project or delete_project to
show the operator exactly what remains pending.
Inputs: no named parameters. Returns: result
list_projectsARead-onlyIdempotent
List registered Hub projects with open/done thread counts.
Use for project discovery or navigation. This is read-only; use
resolve_project or upsert_project when a project needs to be resolved or
changed.
Inputs: limit. Returns: result
list_remindersARead-onlyIdempotent
List persisted Hub reminders without changing them.
Prefer due_only=true at session start to surface only reminders that need
attention now. Set include_handled=true only when historical handled
reminders are relevant.
Inputs: due_only, include_handled. Returns: result
mark_doneADestructive
Close a specific thread when its finishable outcome is complete.
Prefer completion.ready == true (or clear Goal completion) before calling.
Use pause_thread for unfinished work that will resume later, or
dismiss_thread when intentionally abandoning it. note is an optional
completion note. If this call is denied/rejected because work remains,
do not retry unchanged — checkpoint with upsert_progress and pause_thread.
Inputs: thread_id (required), note. Returns: Thread on success; only error and the requested id on rejection/not-found.
pause_threadADestructive
Pause unfinished work and save the concrete next action to resume it.
Use when the thread will continue later (including when completion.ready
is false). This updates its pause/resume state; use mark_done for
completed work or dismiss_thread for work being intentionally abandoned.
Requires the exact thread_id and next_step. Weak wording never blocks the
pause; the response's advisory return_cue says whether next_step names
something specific to open, run or check first.
Inputs: next_step (required), thread_id (required). Returns: object
push_openclaw_memoryA
Best-effort push of a short Hub digest into configured OpenClaw memory.
This has an external side effect and depends on the operator's OpenClaw
integration being configured. It sends a compact Hub-generated digest,
not raw chats; project_slug narrows it and note adds short context.
Inputs: note, project_slug. Returns: object
register_workspaceAIdempotent
Register a local folder as a Hub project in one operation.
Side effect: this persists the workspace/project mapping and, when
create_open_thread=true, also creates a default open thread. Use
resolve_project when you only need to resolve an already-known workspace
or want optional lookup-with-create behavior.
Inputs: workspace_path (required), title, summary, source_tool, +1 more. Returns: object
rename_projectAIdempotent
Queue a project rename for human confirmation in /ui.
Use when the project identity should change. This request does not apply
the rename immediately; list_pending_actions shows queued confirmations.
Inputs: slug (required), new_slug (required), title, reason. Returns: object
report_guidance_healthADestructive
Record versions of Hub guidance a local client actually verified.
Call only after inspecting managed markers or running a local doctor/setup check. The Hub cannot inspect the client's checkout; it replaces the project's last verification record and timestamp with the supplied versions. Null versions mean unavailable, not verified current. Project resolution may create a local registry entry; no guidance files are edited.
Inputs: source, project_slug, workspace_path, cursor_rule_version, +2 more. Returns: Stored client verification record, or error; no client filesystem inspection.
request_thread_mergeAIdempotent
Queue a local duplicate-thread merge for explicit human approval.
This only creates a pending action, never executes a merge. A human must review both states and approve through authenticated REST pending-actions. The target state is kept, the source and all its history are retained. Forge-backed threads cannot be merged. Never approve on the human's behalf.
Inputs: source_thread_id (required), target_thread_id (required). Returns: object
resolve_projectA
Resolve the current Hub project from a workspace path or slug.
Use at session start before session_digest. With create_if_missing=true,
this may create a local project registry entry; false prevents creation.
An existing project_slug with workspace_path still registers that path.
Use upsert_project for explicit metadata or forge configuration changes.
Inputs: title, project_slug, workspace_path, create_if_missing. Returns: Resolved registry project on success; only error on lookup failure.
search_workARead-onlyIdempotent
Search local Hub work without an external index.
Returns mixed hits (thread, project, wiki) with quiet snippets. Read-only; does not create or change threads.
Inputs: query (required), limit, include_done. Returns: object
session_digestADestructive
Build the session-start resume digest for the current work context.
Use after resolve_project. It combines relevant stale/open threads, due
reminders, and the progress wiki snippet; query narrows overlap relevance
and energy can filter work to the operator's current capacity. Each item
carries completion readiness and advisory return_cue coaching for its
resume_step (deterministic, local, never blocking). This is a mutating
session action: it refreshes nudged threads' reminder cooldowns, marks
surfaced non-session reminders fired, and builds a missing wiki index.
Random reminders are sampled, so repeat calls may produce different results.
clock_off is the global opt-in advisory boundary. During winding_down or
clocked_off, avoid substantial new work, finish only a small safe step,
checkpoint with upsert_progress and pause_thread with a concrete resume
step. Respect explicit temporary overrides; no forced shutdown or strict
Continuity Guard is required. Disabled Clock-Off adds no work restrictions.
Includes a `guidance` object (expected versions + last local verification
status). The Hub cannot inspect the client's checkout — run
`adhd-hub doctor --project` locally (or call `report_guidance_health`
after a local check) so this field becomes meaningful.
Inputs: query, energy, workspace_path. Returns: Session summary after reminder cooldown/firing bookkeeping.
set_reminderA
Create and persist a Hub reminder.
kind selects once, session, daily, or random scheduling. A once reminder
requires due_at_iso to become due; future times delay any kind. Use an
ISO datetime with a UTC offset. Each call creates a separate reminder.
Use list_reminders to read existing reminders without creating one.
Inputs: message (required), kind, due_at_iso. Returns: object
snooze_thread_triageADestructive
Snooze stale-thread triage prompts for a few days (default 7).
Soft only — thread stays open. Never auto-dismisses. Use
confirm_thread_relevant when the outcome is still wanted now.
Inputs: thread_id (required), days. Returns: object
suggest_duplicate_threadsCRead-onlyIdempotent
Review overlap suggestions for an existing thread's finishable outcome.
Same-goal evidence is conservative; related work is not a merge candidate. Forge-backed work stays separate and forge-authoritative. No writes.
Inputs: thread_id (required), limit. Returns: object
suggest_next_upARead-onlyIdempotent
Calm cross-project Next-up pick (Wave 7 continuity intelligence).
Soft ranking only — prefers quiet/stale open work with a resume cue,
optional energy match, and optional focus_project_slug to honour focus
mode / drift (stay near the chosen project). Never starts or dismisses
work. Prefer this when focus is off and the human asks “what now?”.
Inputs: energy, project_slug, focus_project_slug. Returns: object
thread_merge_historyARead-onlyIdempotent
Read retained merged threads, progress notes and events with original IDs.
Limit applies per original thread. All source and resume information is retained; this does not fetch or change remote issues.
Inputs: thread_id (required), limit. Returns: object
upsert_progressADestructive
Save a checkpoint to active thread state and project PROGRESS.md.
Prefer a known thread_id so the checkpoint cannot land on the wrong
thread. Update structured Goal/Focus/Next/Blocked/Resume only on routine
checkpoints — do not pass ritual content such as "Thread upserted from …".
Reserve content for rare human-meaningful events (decision, blocker note,
ship note). If selection is ambiguous the tool can request a thread_id;
force_new_thread explicitly starts another outcome. Depending on
create_thread_if_missing, a missing thread may be created as a side effect.
When completion.ready is false, prefer this plus pause_thread over mark_done.
Saving thread progress clears paused_at and may sync to a configured
forge/wiki or refresh scan-line AI. The returned thread.return_cue is
advisory coaching on resume_step (missing / vague / concrete); weak cues
do not reject a save. Name the first action using only facts you know.
Inputs: goal, focus, title, content, +9 more. Returns: Saved checkpoint, ambiguous selection, or error; absent keys stay absent.
upsert_projectADestructive
Create or update a project registry entry and its explicit metadata.
Use when setting title, workspace path, repository, energy, parent, or forge
targeting. parent_slug nests under any project (unlimited depth; cycles rejected).
This persists local Hub project configuration; it does not by itself create,
rename, or delete a remote forge repository.
Inputs: title (required), slug, energy, repo_url, +7 more. Returns: object
upsert_threadADestructive
Create a new finishable work thread or explicitly update one.
One thread should represent one independently finishable outcome, not a
whole project. Pass thread_id when updating a known thread. For routine
checkpoints on active work, prefer upsert_progress so progress notes and
PROGRESS.md stay in sync. Without thread_id, a generated ID may match and
update an existing thread. Updates apply the status and energy defaults;
supplied progress fields clear paused_at. Writes update progress/wiki
files and may sync to a configured forge or refresh scan-line AI.
Inputs: summary (required), goal, focus, energy, +10 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Several clusters overlap: suggest_duplicate_threads / check_overlap / search_work all answer 'is this already being worked on', and get_overview / session_digest / suggest_next_up / list_open_threads all answer 'what should I do next'. Likewise resolve_project (with create_if_missing), upsert_project, and register_workspace are three different ways to end up with a project registry entry. The descriptions do heavy cross-referencing to steer selection, which keeps this from being worse, but the agent still has to read carefully to pick correctly.
Nearly everything follows a snake_case verb_noun pattern (list_open_threads, upsert_progress, mark_done, pause_thread, set_reminder, report_guidance_health). Two outliers — thread_merge_history and session_digest — drop the verb prefix and are named as nouns, but they remain readable and unambiguous.
At 27 tools this sits above the comfortable 3-15 band and each tool requires real reading to use correctly. The breadth is justified by several distinct sub-domains (threads, projects, reminders, triage, session digest, guidance, external integration), but consolidation of the overlap/search surfaces would materially shrink the set.
Thread lifecycle is genuinely complete (create, progress, done, pause, dismiss, triage confirm/snooze, merge request/history), and projects have list/resolve/upsert/rename/delete/register. However reminders only have set_reminder and list_reminders — there is no update, cancel/delete, or explicit mark-handled operation despite include_handled implying handled state. There is also no way to cancel a queued pending action, only list it.
Maintenance
Related MCP Connectors
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Hosted memory for your AI coding agents. Projects, decisions, to-dos and lessons that carry across Claude, Cursor and ChatGPT. Nothing to install: sign in at flowstatemcp.com and connect. Encrypted at rest, backed up, export or erase any time. Beta: 6 months free, then half price.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenancePersistent memory and task coordination for AI coding agents. Tracks sprint items, logs tasks, manages session handoffs, and surfaces HITL requests so you stay in control across single or parallel Claude Code, Codex, Cursor, and Windsurf sessions.-
- AlicenseAqualityBmaintenanceLocal-first shared memory and task coordination for AI coding agents. One Go binary, MCP server, markdown files you own. Hooks for Claude Code and Codex CLI (and their desktop apps).306MIT
- AlicenseBqualityBmaintenanceLets multiple AI agents and parallel coding sessions share one memory and task ledger, so they can claim work instead of duplicating it, resume each other's handoffs and reasoning, and use credentials without ever seeing the keys. Connects assistants such as Claude Code, Codex, Cursor, Gemini, ChatGPT and custom agents over MCP, backed by a single local SQLite file or a self-hosted Postgres hub.411MIT
- AlicenseNot gradedqualityCmaintenancePersistent project memory and task management for AI coding agents through MCP. Lets Claude Code, Cursor, Codex and other MCP clients save decisions and bug fixes, search relevant context, and reuse it across sessions.1MIT



