{
  "markdown": "<p align=\"center\">\n  <img src=\"./assets/icon-512.png\" alt=\"NeuroDock\" width=\"180\">\n</p>\n\n<h1 align=\"center\">NeuroDock</h1>\n\n<p align=\"center\"><em>A cognitive substrate that remembers, paces, and refuses. Built with neurodivergent professionals, not for them.</em></p>\n\n<p align=\"center\">\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-AGPL--3.0--or--later-1f1f1f.svg\" alt=\"License AGPL-3.0-or-later\"></a>\n  <img src=\"https://img.shields.io/badge/python-3.11%2B-1f1f1f.svg\" alt=\"Python 3.11+\">\n  <img src=\"https://img.shields.io/badge/node-22%2B-1f1f1f.svg\" alt=\"Node 22+\">\n  <a href=\"https://www.npmjs.com/package/@neurodock/cli\"><img src=\"https://img.shields.io/npm/v/@neurodock/cli?label=%40neurodock%2Fcli&color=1f1f1f\" alt=\"@neurodock/cli on npm\"></a>\n  <a href=\"https://pypi.org/project/neurodock-mcp-chronometric/\"><img src=\"https://img.shields.io/pypi/v/neurodock-mcp-chronometric?label=pypi%3A%20mcp-servers&color=1f1f1f\" alt=\"neurodock-mcp-* on PyPI\"></a>\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/cross--platform-macos%20%C2%B7%20linux%20%C2%B7%20windows-1f1f1f.svg\" alt=\"Cross-platform\">\n  <img src=\"https://img.shields.io/badge/MCP-native-1f1f1f.svg\" alt=\"MCP-native\">\n  <img src=\"https://img.shields.io/badge/local--first-default-1f1f1f.svg\" alt=\"Local-first by default\">\n  <img src=\"https://img.shields.io/badge/telemetry-none-1f1f1f.svg\" alt=\"No telemetry\">\n  <img src=\"https://img.shields.io/badge/self--ID-sufficient-1f1f1f.svg\" alt=\"Self-ID sufficient\">\n</p>\n\n## 5-second TL;DR\n\n- **What it does:** gives Claude a memory of your work, a sense of time, a refuse-rumination guardrail, and a translator for corporate ambiguity.\n- **Who it's for:** neurodivergent people — self-ID only, no diagnosis required, no gatekeeping.\n- **How to install:** one command, below.\n\nNeuroDock plugs into Claude Desktop / Claude Code / Cursor (any MCP-aware\nclient). Local-first by default. No telemetry. AGPL-3.0-or-later.\n\n## How it fits together\n\nYou chat with Claude exactly like normal. Under the hood, Claude calls\nNeuroDock's local MCP servers; they read and write your local store; the\nresult flows back into Claude's reply.\n\n<p align=\"center\">\n  <img src=\"./assets/branding/architecture-request-path.svg\" alt=\"Request path: you talk to Claude; Claude calls five NeuroDock MCP servers (chronometric, cognitive-graph, task-fractionator, translation, guardrail) plus the evals harness; they read and write ~/.neurodock on your local machine; results flow back into Claude's reply. All local by default, no telemetry, your data stays your data.\" width=\"100%\">\n</p>\n\nEverything runs on your laptop. Nothing leaves your machine unless you\nexplicitly turn on a cloud option.\n\n<p align=\"center\">\n  <img src=\"./assets/branding/onboarding-3-steps.svg\" alt=\"Install NeuroDock in three steps: 1) Run npx @neurodock/cli@latest install-all (under 5 minutes). 2) Full-quit Claude with Cmd+Q or Ctrl+Q so it re-reads its MCP config (30 seconds). 3) Start talking to Claude — for example, ask 'What was I working on yesterday?'\" width=\"100%\">\n</p>\n\n## Install\n\n```sh\nnpx --yes @neurodock/cli@latest install-all\n```\n\nOne command. It pip-installs the five MCP servers (plus the `neurodock-evals`\nharness), wires Claude Desktop / Claude Code / Cursor, and drops a starter\nprofile at `~/.neurodock/profile.yaml`.\n\nThen, **in any conversation**, try one of:\n\n```\nWhat was I working on yesterday?\nPlan my morning.\nDecompose this goal into atomic tasks.\n```\n\nClaude calls the MCP tools under the hood; you just talk.\n\n> ### 🛑 First-time gotcha: full-quit Claude before testing\n>\n> Claude only reads its MCP config at startup. **Closing the window is not\n> enough.** This is the #1 silent failure people hit.\n>\n> - **macOS:** `Cmd + Q` (or Claude menu → Quit Claude).\n> - **Windows:** right-click the Claude icon in the system tray → **Quit**.\n> - **Linux:** kill the process (`pkill -f Claude` or quit from the tray).\n>\n> Then reopen Claude and try one of the prompts above.\n\nRequires Python 3.11+ and Node 22+. Works on macOS, Linux, Windows.\n\n> **Why `@latest`?** If you previously ran `npm install -g @neurodock/cli`,\n> npx will silently reuse that older global install instead of fetching the\n> current version — and old versions don't have `install-all`. The `@latest`\n> tag forces npx to resolve against the npm registry every time. Same reason\n> we use it on `update`.\n\n<details>\n<summary><strong>Want to install it step-by-step instead?</strong></summary>\n\nNeuroDock ships across two registries: the Python **MCP servers** (MCP =\nModel Context Protocol — the standard that lets Claude call local tools)\non PyPI, and the user-facing **CLI** on npm. The CLI wraps everything else.\n\n**1. Install the six MCP servers**\n\n```sh\npip install neurodock-mcp-chronometric neurodock-mcp-cognitive-graph neurodock-mcp-task-fractionator neurodock-mcp-translation neurodock-mcp-guardrail neurodock-evals\n```\n\n**2. Wire them into your MCP-aware client**\n\n```sh\nnpx --yes @neurodock/cli@latest init\n```\n\nDetects Claude Desktop, Claude Code, or Cursor and writes the server\nentries automatically.\n\n**3. Restart Claude** (full quit, not close-window — see the callout above).\n\n**About the `neurodock` command** — it lives on npm as `@neurodock/cli`,\n**not** on PyPI. The `pip install` step gives you the MCP server binaries\nthat Claude calls over stdio; the CLI is separate. Two ways to run it:\n\n```sh\n# Option A — run via npx, no install\nnpx --yes @neurodock/cli@latest doctor\n\n# Option B — install once, call 'neurodock' from anywhere\nnpm install -g @neurodock/cli\nneurodock doctor\n```\n\n`@neurodock/cli` exposes: `init`, `doctor`, `validate`, `update`, `sync`,\n`uninstall`, `host install`, `host uninstall`, `profile show`,\n`profile validate`, `install-all`, `install-hooks`, `examples`,\n`plugin add/remove/list/enable/disable/validate`.\n\n### Proactive guardrails (optional, recommended)\n\nBy default NeuroDock waits for you to ask. That's the wrong shape — an\nND user in hyperfocus is the one least likely to remember to run a\nbreak tool. One command flips it:\n\n```sh\nneurodock install-hooks --self-test\n```\n\nThis wires a small Python script (bundled, stdlib-only — no extra\ninstall needed) into Claude Code's hook system. It then runs silently\non every tool call and auto-fires the chronometric / rumination /\nsycophancy heuristics when patterns trip. You get a one-line stderr\nbanner on the next prompt — never blocked, always dismissible.\n\nFor host-agnostic coverage (catches you working in the terminal at\n02:00 too), add the standalone daemon:\n\n```sh\nneurodock install-hooks --install-daemon --self-test\n```\n\nThat registers a per-user autostart entry (HKCU Run on Windows,\nLaunchAgent on macOS, systemd `--user` on Linux). The daemon polls\nevery 5 min and surfaces OS-native notifications.\n\nOpt out anytime:\n\n```sh\nneurodock install-hooks --uninstall          # removes both\nexport NEURODOCK_GUARDRAILS=off              # disables without removing\n```\n\nThe browser extension carries its own equivalent (Phase 2 watchdog) —\nit's enabled by default and toggleable from `chrome.storage.local` via\nthe popup Settings tab.\n\nSee [`docs/.../proactive-guardrails`](./docs/src/content/docs/concepts/proactive-guardrails.mdx) for the design behind this and the\nopt-out matrix.\n\nWant to see it work without installing from PyPI/npm at all?\n`TESTING_LOCAL.md` walks through the from-clone path.\n\n</details>\n\n<details>\n<summary><strong>Prefer a plugin, a one-click desktop extension, or the MCP Registry?</strong></summary>\n\nThe `install-all` command above is the recommended path. The same servers are\nalso distributed through three standard channels — all install the identical\nlocal stdio servers, so you can pick whichever fits your client:\n\n**Claude Code plugin** — bundles the five MCP servers _and_ a set of ND-aware\nskills in one step. Requires [`uv`](https://docs.astral.sh/uv/) (the servers\nrun via `uvx`).\n\n```\n/plugin marketplace add tlennon-ie/neurodock\n/plugin install neurodock@neurodock\n```\n\n**Claude Desktop extension (`.mcpb`)** — one-click install, no config editing.\nOne bundle per server under [`mcpb/`](./mcpb/); build with\n`npx @anthropic-ai/mcpb pack mcpb/neurodock-mcp-translation` and drag the\n`.mcpb` onto Claude Desktop → Settings → Extensions. Requires `uv`.\n\n**Official MCP Registry** — each server ships a\n[`server.json`](./packages/mcp-translation/server.json) and is published to\n[registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)\nunder the `io.github.tlennon-ie/*` namespace, so MCP-aware clients can discover\nthem directly.\n\n**Hosted remote server (no install)** — the stateless tools (translation,\nguardrail, and `decompose`) are also served over OAuth at a hosted HTTPS\nendpoint, so you can use them with no local install and no `uv`:\n\n```\nhttps://mcp.neurodock.org/mcp\n```\n\nIn Claude (claude.ai or Desktop) → **Settings → Connectors → Add custom\nconnector** → paste that URL → complete the sign-in prompt. The eight stateless\ntools appear immediately. An opt-in memory surface (`enable_hosted_storage`,\n`connect_byos_storage`, `record_fact`, `recall_entity`, …) is also exposed but\ndoes nothing until you explicitly enable storage for your signed-in account. The\npersonal cognitive graph and neurotype profile are **never** hosted — they stay\non the local install. Full walkthrough: [Hosted server](./docs/src/content/docs/getting-started/remote.mdx).\n\nThe hosted remote server is live at `mcp.neurodock.org`.\n\n</details>\n\n## Update\n\n```sh\nnpx --yes @neurodock/cli@latest update\n```\n\nOne command. Upgrades all six MCP servers (`pip install --upgrade` /\n`uv tool install`), refreshes your wired client configs, and\nre-registers the optional native-messaging host. Same flags as\n`install-all` (`--client`, `--profile`, `--installer`, `--dry-run`,\n`--no-native-host`, `--yes`).\n\nThe browser extension auto-updates through the Chrome / Firefox / Edge\nstore; sideloaded users `git pull` and rebuild.\n\n> Full-quit Claude after updating so it re-reads its MCP config — same\n> as first install.\n\nJust want to re-shape client configs without touching package versions?\nUse `neurodock sync`.\n\n## See it in action\n\n**The cognitive substrate in a real session** — you talk to Claude normally;\nunder the hood it calls NeuroDock's MCP tools to remember, pace, and decompose.\n\nhttps://github.com/user-attachments/assets/bcbf65ce-88dd-4f83-8dc1-d56bdde01bed\n\n**The browser extension** — translating corporate-speak inline on Gmail, Slack,\nand the rest, right where you read it, without context-switching back to Claude.\n\nhttps://github.com/user-attachments/assets/5fa25044-923e-4c25-95bd-f1bd63fb3d6e\n\n> Prefer a written walkthrough? Try the [Claude Desktop walkthrough](./examples/claude-desktop/README.md).\n\n## Browser extension (optional)\n\nThere's also a browser extension that translates corporate-speak inline on\nGmail, Slack, Linear, Notion, GitHub, Google Docs, and Outlook. It calls\nthe same translation tools the MCP server exposes, but surfaces them\nwhere you'd actually use them — a floating Translate button plus a\nright-click menu — so you don't have to context-switch back to Claude\njust to decode \"let's circle back on this.\"\n\nYou pick the LLM provider. Five options: Ollama (local, default), LM\nStudio (local), OpenRouter (including its auto-router), Anthropic, OpenAI.\nThe API key, if you need one, stays in `chrome.storage.local` and never\nleaves the device.\n\nStore submission is still pending (the listing prep is done; the developer\naccounts and screenshots aren't). Until then, load it manually:\n\n1. Build it: `pnpm --filter @neurodock/extension-browser run build`\n2. Chrome / Edge: go to `chrome://extensions`, turn Developer mode on,\n   click **Load unpacked**, and pick `packages/extension-browser/.output/chrome-mv3/`.\n3. Firefox: go to `about:debugging`, click **This Firefox** → **Load\n   Temporary Add-on**, and pick `manifest.json` inside\n   `packages/extension-browser/.output/firefox-mv3/`.\n\nFull per-provider setup walkthrough lives in\n[`packages/extension-browser/README.md`](./packages/extension-browser/README.md).\n\n## What's inside\n\nNeuroDock is built around three pillars. Each pillar is made of small,\nindependent packages that you can use one at a time or all together.\n\n```mermaid\nflowchart TB\n  subgraph cognitive[Cognitive substrate]\n    chrono[mcp-chronometric<br/>time + sessions]\n    cgraph[mcp-cognitive-graph<br/>memory]\n    frac[mcp-task-fractionator<br/>decomposition]\n  end\n  subgraph comms[Communication layer]\n    trans[mcp-translation<br/>tone + meetings]\n    ext[extension-browser<br/>Gmail, Slack, ...]\n  end\n  subgraph safety[Clinical guardrails]\n    guard[mcp-guardrail<br/>rumination / hyperfocus / sycophancy]\n    clin[clinical<br/>heuristic library]\n  end\n  skills[skills/<br/>six markdown bundles] --> cognitive\n  skills --> comms\n  skills --> safety\n  cli[cli/<br/>install + manage] --> cognitive\n  cli --> comms\n  cli --> safety\n```\n\n<details>\n<summary>Prefer the directory tree? Open this.</summary>\n\n```\nneurodock/\n├── packages/\n│ ├── mcp-chronometric/      Time + session + break management\n│ ├── mcp-cognitive-graph/   Persistent memory + entity recall (SQLite)\n│ ├── mcp-task-fractionator/ Decompose vague goals into atomic tasks\n│ ├── mcp-translation/       Corporate-speak translator (MCP + browser ext)\n│ ├── mcp-guardrail/         Rumination / hyperfocus / sycophancy detectors\n│ ├── skills/                Six SKILL.md bundles activating on phrases\n│ ├── extension-browser/     WXT-built Chrome / Firefox / Edge extension\n│ ├── native-host/           Optional native messaging host (extension <-> profile.yaml)\n│ ├── cli/                   `npx neurodock init` and friends\n│ ├── core/                  Shared types, profile schema, plugin spec\n│ ├── clinical/              Heuristic library for the guardrail server\n│ └── evals/                 Eval harness + corpus contribution pipeline\n├── docs/                    Astro Starlight site (deploys to docs.neurodock.org)\n├── plugins/                 Drop your own plugins here; auto-discovered\n└── profiles/                Curated profile presets\n```\n\n</details>\n\n## Status\n\n**Public preview shipped.** All three substrate pillars (cognitive,\ncommunication, guardrails) are built, on `main`, and installable from\nnpm + PyPI. Latest substrate tag: `v0.7.3`.\n\n### MCP servers (PyPI)\n\n- **`neurodock-mcp-chronometric`** — 5 tools, 22 tests, mypy `--strict`.\n- **`neurodock-mcp-cognitive-graph`** — 4 tools, SQLite + sqlite-vec\n  - fastembed; 4-rung resolution cascade (exact → alias → fuzzy → embedding).\n    Latest patch ships friendlier `record_fact` errors so wrong-shape input\n    no longer leaks raw Pydantic traces.\n- **`neurodock-mcp-task-fractionator`** — 2 tools, 32 tests; ISO 8601\n  duration spec.\n- **`neurodock-mcp-translation`** — 4 tools, 29 tests; deterministic\n  baseline plus LLM refinement envelope.\n- **`neurodock-mcp-guardrail`** — all three detectors live: rumination,\n  hyperfocus, sycophancy (48 tests, public heuristics).\n- **`neurodock-evals`** — air-gapped harness, 10 seed corpus examples,\n  contribution pipeline.\n- **`neurodock-clinical`** — reserved name; importable detector library\n  (currently a stub).\n\n### CLI + browser surface (npm)\n\n- **`@neurodock/cli`** — 19 verbs across 7 groups: `init`, `install-all`,\n  `examples`, `doctor`, `validate`, `update`, `sync`, `uninstall`,\n  `host install/uninstall`, `profile show/validate`, `install-hooks`,\n  `plugin add/remove/list/enable/disable/validate`. `install-hooks`\n  wires the proactive-guardrail hook into Claude Code and optionally\n  registers the standalone daemon.\n- **`@neurodock/core`** — profile schema and plugin protocol manifests\n  (JSON Schema 2020-12).\n- **`@neurodock/native-host`** — optional Chrome Native Messaging host\n  for the extension ↔ profile sync.\n- **`@neurodock/extension-browser`** — WXT MV3 build for Chrome / Firefox\n  / Edge. Seven sites wired. Five real LLM providers: Ollama, LM Studio,\n  Anthropic, OpenAI, OpenRouter. Includes the Phase 2 proactive watchdog\n  for hyperfocus / late-night / single-host rumination signals.\n  **Not yet store-published.**\n\n### Skills + docs\n\n- **Six launch skills** — `adhd-daily-planner`, `audhd-context-recovery`,\n  `ocd-decision-finalizer` (beta), `hyperfocus-formatter`, `visual-organizer`,\n  `asd-meeting-translator`.\n- **Docs site** — builds clean (Astro Starlight), deploys to\n  [`docs.neurodock.org`](https://docs.neurodock.org).\n\n### Still deferred\n\n- **Browser-store submissions** — Chrome Web Store, Firefox Add-ons, Edge\n  Add-ons developer accounts + screenshots; manual step.\n\n## How to actually test it right now\n\n**`TESTING_LOCAL.md`** — step-by-step guide to running this against your\nClaude Desktop, today, from a clone. Takes about 5 minutes.\n\n## Documentation\n\nThe docs site lives at [`docs.neurodock.org`](https://docs.neurodock.org).\nSource is at `docs/src/content/docs/`. To preview locally:\n\n```bash\npnpm --filter @neurodock/docs run dev\n# opens http://localhost:4321\n```\n\n## Architecture\n\nThe substrate splits into three pillars:\n\n1. **Cognitive substrate** — externalises executive function (time,\n   memory, decomposition). MCP servers: chronometric, cognitive-graph,\n   task-fractionator.\n2. **Communication layer** — translates corporate ambiguity; rewrites\n   outgoing messages for register-appropriate tone; structures meeting\n   transcripts. MCP server: translation. Browser extension surfaces the\n   same prompts in Gmail / Slack / Linear / Notion / GitHub / Docs / Outlook.\n3. **Clinical guardrails** — detects and intervenes on rumination\n   (repeat-validation loops), hyperfocus (escalating session-length\n   nudges), and sycophancy (unconditional agreement). MCP server: guardrail.\n   Heuristics are public and auditable per `ETHICS.md`.\n\nAll three layers compose via the same MCP protocol the LLM client already\nspeaks. There's no \"NeuroDock app\" — the surface is your Claude client.\n\nDesign rationale lives in `docs/decisions/`:\n\n- ADR 0001 — chronometric tool design\n- ADR 0002 — cognitive-graph tool design\n- ADR 0003 — task-fractionator tool design\n- ADR 0004 — profile schema\n- ADR 0005 — translation tool design\n- ADR 0006 — guardrail tool design\n- ADR 0007 — plugin protocol\n- ADR 0008 — distribution & remote strategy\n\n## Contributing\n\n`CONTRIBUTING.md` has the welcome + on-ramp. Pick whichever lane matches\nwhat you want to do:\n\n**Smallest first PR (~15 min):**\n\n- Add a test to an existing skill (`packages/skills/<name>/tests/`)\n- Add a seed eval example (`packages/evals/corpora/translation/`)\n- Improve a tool's parameter description (the LLM uses these — clearer\n  descriptions = better tool use)\n\n**One-afternoon PR:**\n\n- Write a new skill — markdown bundle activating on specific phrases.\n  Copy any `packages/skills/<name>/` as a template; see\n  `docs/src/content/docs/contribute/write-a-skill.mdx`.\n- Sharpen the task-fractionator heuristics (regex / domain keyword maps).\n- Add a new entity-resolution heuristic (e.g., phonetic) to\n  `mcp-cognitive-graph`.\n\n**Multi-day PR:**\n\n- Build an out-of-tree plugin (skill / mcp-server / profile / translation\n  pack / language pack / theme) per the ADR 0007 plugin protocol. See\n  `docs/src/content/docs/contribute/write-a-plugin.mdx`.\n- Translation language pack (e.g., Hiberno-English, German directness norms,\n  Japanese keigo).\n\n**No code:**\n\n- Add an anonymised eval example from your own corporate inbox. The\n  contribution pipeline lives in `packages/evals/` and is the highest-\n  leverage non-code contribution.\n\nAll PRs run CI: `pnpm turbo run lint typecheck test build` + `uv run pytest`\n\n- `uv run mypy --strict packages/...`. Every published package has its\n  own CHANGELOG. Use Conventional Commits in PR titles (`feat:`, `fix:`,\n  `docs:`, `test:`, `chore:`, `ci:`).\n\n## Manifesto (short)\n\n1. **Lower friction for users, and for contributors.**\n2. **Local-first by default; cloud is opt-in.**\n3. **The user is the authority.** Self-ID sufficient.\n4. **Composable over monolithic.** No god-modules.\n5. **Refuse where appropriate.** AI that fuels rumination, hyperfocus, or\n   anxiety is a regression, not a feature.\n\nFull text in `MANIFESTO.md`. Ethics framework in `ETHICS.md`. Governance\nin `GOVERNANCE.md`.\n\n## License\n\n[AGPL-3.0-or-later](LICENSE). Plugins must declare an AGPL-compatible license\nto load — the SPDX whitelist is in ADR 0007.\n",
  "bytes": 20391,
  "sha": "c6c59a271e5c757d28a948eadb8e09d1b6ad7637c53b3471168bbb0194cc45f9",
  "repo_slug": "tlennon-ie/neurodock",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tlennon_ie_neurodock_mcp_cogni_ac23b643/readme"
}