uniskela/adhd-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.
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/ /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:
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
Local MCP over stdio
For MCP clients that launch a local subprocess, the same Hub tool catalog can run over stdio:
Generic MCP config:
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.20.2, 0.20)
**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.
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).