Skip to main content
Glama

ADHD Progress Hub

Coded with Codex Coded with Cursor ADHD Progress Hub MCP server – quality and maintenance score on Glama

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):

My work with Notes & context

Now

My work

Progress

Settings

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.md

  • Overlap 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/health

For 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 8787

Local MCP over stdio

For MCP clients that launch a local subprocess, the same Hub tool catalog can run over stdio:

adhd-hub mcp-stdio

Generic 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, and X.Y on the Git tag created for that release (for example 0.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.1

Repo 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 -g

Or 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/mcp

  • MCP (optional local subprocess transport): adhd-hub mcp-stdio

  • REST docs: http://<host>:8787/docs

  • UI: http://<host>:8787/ui/

MCP tools

Tool

Purpose

session_digest

Compact open threads (goal/focus/next/resume) + reminders

check_overlap

Rank open threads vs what you’re starting (goal/title/focus)

suggest_duplicate_threads

Review same-outcome evidence and safe merge eligibility

request_thread_merge

Queue a local duplicate merge for explicit human confirmation

thread_merge_history

Read retained source threads, notes and events under their original IDs

resolve_project

Map workspace path → project slug

list_projects / upsert_project

Project registry (+ optional forge overrides)

rename_project / delete_project

Queue rename/delete for /ui confirmation (not applied immediately)

list_pending_actions

See delete/rename requests waiting for you

list_open_threads

List unfinished work

upsert_thread

Create/update a thread (one finishable outcome)

upsert_progress

Update thread state + PROGRESS.md (thread_id when known)

pause_thread

Leave a concrete resume step

mark_done

Close a known thread

set_reminder

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 openclaw

Pairing (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/agent

Environment 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 index

Roots (override in config.toml [indexer]):

  • Cursor: ~/.cursor/projects/**/agent-transcripts/**/*.jsonl

  • Codex: ~/.codex/sessions/**/*.jsonl

  • Claude 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 id

  • Primary memory repo — seeds README.md / AGENTS.md; leave Wiki path blank so files land at projects/<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, with ADHD_HUB_AUTH_TOKEN for 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 with python -c "import secrets; print(secrets.token_urlsafe(32))". Use HTTPS for remote access.

  • Cookie-authenticated writes require X-Hub-Request: 1 and 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_URL sets the externally reachable Hub base URL used for browser/deep links, forge links, install/connect output, and MCP OAuth discovery.

  • Bind 127.0.0.1 for local-only, or Tailscale-only — do not expose publicly without a reverse proxy / tunnel terminator and strong token (Remote MCP access)

  • Migrate instances with /ui backup 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

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/project

Add --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 | iex

The 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/project

connect 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,claude

Roadmap

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 tests

See 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 tools
check_overlapA
Read-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_relevantA
Destructive

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_projectA
Idempotent

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_threadA
DestructiveIdempotent

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_overviewA
Read-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_threadsA
Read-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_actionsA
Read-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_projectsA
Read-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_remindersA
Read-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_doneA
Destructive

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_threadA
Destructive

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_workspaceA
Idempotent

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_projectA
Idempotent

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_healthA
Destructive

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_mergeA
Idempotent

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_workA
Read-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_digestA
Destructive

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_triageA
Destructive

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_threadsC
Read-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_upA
Read-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_historyA
Read-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_progressA
Destructive

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_projectA
Destructive

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_threadA
Destructive

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

    A3.5/5.0

    Scored across 27 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Persistent 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.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Local-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).
      30
      6
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Lets 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.
      41
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent 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.
      1
      MIT