CoMind: team-shared AI context for Claude Code

The problem

Put three developers on one repo with Claude Code and you get three private contexts that drift apart from day one.

Every session re-derives the same architecture facts. Verbose tool output eats the budget. Nothing survives the session: no shared spec memory, no deterministic verification, nothing compressed.

CoMind is glue. It reimplements none of the tools it uses. It installs them at pinned versions, wires them so they compose instead of colliding, and manages the Git layout that makes the result shared.

Two stages, on purpose

Stage 1: install CoMind

npx -y @comind-dev/comind@latest   # your repo is not touched

This registers CoMind as a Claude Code plugin, which is what gets you claude plugin update / uninstall / disable / details and a real version registry. Four slash commands show up, costing roughly 200 always-on tokens. It installs no tools, and nothing in your repo or your config changes. Safe to run again and again.

If the claude CLI isn't on PATH it falls back to copying into ~/.claude/comind/pkg/. That works. It also has no update or uninstall path, and comind doctor says so rather than pretending otherwise.

Stage 2: set up the project

/comind-init   # run inside a Claude Code session

All the real work happens here, and it has to. Project setup needs a reasoning agent: GSD onboarding maps the codebase with subagents and asks you what the project is actually for. A shell script can do neither. And a .planning/ written from a script's assumptions is precisely the context rot CoMind exists to prevent.

Stage 2 works out on its own whether you're bootstrapping the repo or joining one a teammate already set up. Joining writes only machine-local files, so after it runs git status --porcelain comes back empty.

Later, to pick up a new alpha: comind update, restart Claude Code, then /comind-init once per repo. That upgrades CoMind and nothing else. The pinned tool versions live in the repo's committed manifest and belong to the team, so moving them is a separate reviewed commit.

The five layers

Input compression: RTK Rewrites Bash calls (git status → rtk git status) so verbose output is filtered before it reaches context.
Output compression: Caveman Cuts Claude's own output tokens.
Phase discipline: GSD Core Discuss → Plan → Execute → Verify → Ship, with heavy work in fresh-context subagents.
Shared memory: graphify + .ai-memory/ A queryable knowledge graph, exported as a Git-tracked Obsidian vault. A clone can query it without paying to rebuild.
Verification: Anthropic's LSP plugins Real language-server diagnostics for the languages this repo actually has. 12 are supported, and only the ones it contains get installed.

One of these five is enforced. The other four are instructions. The gate hook and the permissions.deny rules are the only parts Claude Code cannot ignore. Phase discipline, retrieval order and verification order all live in a skill file, and they work only if the model follows them. Worth knowing before you rely on any of it.

What gets committed

The split is the whole design. It's why setup is safe to re-run, and why a teammate joining doesn't dirty the repo.

Shared, in Git

.comind/manifest.json pinned versions + enabled layers
.planning/ specs, phases, roadmap
.ai-memory/ derived Obsidian vault
.claude/ gate hook, skills, commands, agents, the GSD engine and its scripts
graphify-out/ the queryable graph and its sidecars
.gitignore .gitattributes managed blocks

Yours alone

.comind/state/ session counters, bypass log
graphify-out/graph.html free local re-render
graphify-out/cache/ extraction cache
*.local.md scratch notes, never reach the vault
~/.claude/comind/bin/ the rtk binary, shared per machine

Commands

Slash commands are the intended interface. The CLI underneath is what they invoke.

/comind-init: Set up or join a repo. Owns the whole flow: tools → hooks → onboarding → graph → vault → git informer.
/comind-sync: After a pull or a shipped phase. Rebuilds the graph, regenerates the vault.
/comind-lsp: Show which language-server plugins this repo needs; install or remove them.
/comind-doctor: Verify all five layers and report version drift. Read-only.

Autocomplete shows /comind:comind-init, because Claude Code namespaces plugin commands and the files carry the name as well. /comind-init is the shorthand and the form used here. It is also the exact name on the file-copy fallback, where there is no plugin namespace to prefix.

Add --dry-run to any CLI command to see every action without writing anything.

Versions are pinned where it matters

versions.json is the single source of truth, and each tool declares how strictly it is held. Nothing resolves latest at install time.

Exact for rtk, gsd-core and caveman. Drift there corrupts the shared repo. rtk is a binary CoMind executes, gsd-core writes committed files, caveman installs hooks into ~/.claude.
Floor (>=) for graphify and the LSP servers. Machine-local, derived output. Nobody's repo changes because a teammate has a newer graphify.

RTK is fetched from its GitHub release and verified against that release's own checksums.txt. Caveman installs from a pinned commit, because tags move.

Requirements

Node: ≥ 18. Everything runs on Node built-ins, so there are zero npm dependencies.
git: The whole point is sharing context through your repo.
Platforms: macOS and Linux, tested.Windows is not supported yet. The win32 code paths exist and their pure logic is unit-tested, but CoMind has never been run end to end on a real Windows host. Treat it as unverified. It may work; if it doesn't, that's expected rather than a surprise.
Optional: The claude CLI, python3 or uv, and a language server per language. Missing one skips that layer and prints the fix. It never fails the whole setup.