mclaude is a small, file-based system that gives your Claude Code sessions a shared notebook, a shared lock box, a shared memory shelf and a shared address book — so two chats, two teammates or two laptops can work on the same project without stepping on each other. Plain markdown and JSON. No server, no database required.
pip install to a working parallel-session demo$ pip install mclaude && mclaude demo --no-pause # ~30 s · spins up two simulated sessions, writes a Mermaid diagram of everything that happened
When you have two Claude chats on the same project — or two teammates running Claude Code, or yourself switching between laptops — you hit the same three questions. mclaude makes the answers readable files on disk that every session sees.
auth/middleware.py.fix-auth-race. A lock file appears in .claude/locks/.Use one layer, or all six. They don’t depend on each other — if you only want handoffs, handoffs work alone. Everything lives as markdown and JSON inside .claude/, so you can read it with any text editor.
Atomic file creation. Two sessions race for the same slug — the OS guarantees only one wins. A 30-second heartbeat proves the holder is alive; silent for 3 minutes and the lock becomes reclaimable.
mclaude lock claim --slug fix-auth-race \
--description "Race in session write"
One file per session with a unique, collision-free name. Every handoff has Goal, Done, What did NOT work, Current state, Key decisions and Next step — so tomorrow’s session never repeats yesterday’s dead ends.
.claude/handoffs/
2026-04-09_14-32_373d_fix-auth-race.md
Decisions, gotchas and references stored as nested markdown — wings, rooms, drawers. Raw verbatim, never summarised. Old decisions are marked superseded_by, never deleted.
mclaude memory search "JWT"
→ wings/project-myapp/rooms/auth-system/
decisions/2026-04-09_use-jwt.md
Map human-friendly names to Claude instances. Sessions stop being bare UUIDs and become ani, vasya, infra, design. Route notifications, attribute handoffs, read a real address book.
mclaude identity register ani \
--owner "Anastasia" --roles infra ml
Live inter-session messaging. Questions, answers, broadcasts, acks — all append-only markdown with frontmatter. A UserPromptSubmit hook delivers new mail on every prompt. Same format works on hub + local.
mclaude mail ask vasya \
"What's the API schema for auth?"
AST-based scanner produces code-map.md (human-readable architecture) and llms.txt (agent-optimised index). New sessions skip the 15-minute “let me re-read the codebase” ritual.
mclaude index
[index] 47 modules · 289 classes · 1,143 fns
Periodic liveness signal per session. Running sessions write a small JSON file with last_beat, current activity, and held locks. Other sessions see who is live versus stale. Same pattern as Kubernetes liveness probes, file-based instead of network-based.
beat(project_root, "ani", "sess-1",
activity="running tests")
[heartbeat] 2 live · 0 stale
Before you commit to reading seven layers of documentation, run mclaude demo.
It spins up a temp directory, walks two simulated sessions — ani and vasya — through every
coordination primitive, and writes a Mermaid sequence diagram of what happened.
Nothing is mocked. Every file on the right is a real file on disk after the run.
You don’t need mclaude if you only ever run one Claude chat — but most people lose context between sessions anyway, so handoff alone is worth it. Add layers as your team grows.
Install mclaude. At the end of a long session, say “prepare handoff”. The next session reads it automatically via the SessionStart hook.
Open a second chat, tell it to “claim work on X”. If chat #1 is still on that slug, chat #2 sees the lock and asks you what to do.
Commit .claude/ to git. Every teammate registers a unique identity. Handoffs become team memory; the memory graph becomes living documentation.
mclaude coordinates who does what, when. claude-code-config codifies what good work looks like — 17 architectural principles, 5 ready-to-use safety hooks, skills, templates and side-by-side comparisons of alternative approaches. Parallel sessions especially benefit from its destructive-command guard, git-destructive guard and auto-backup hooks: mclaude coordinates access, claude-code-config protects the shared state.
Paste this line into a Claude Code chat and the agent walks the repository, picks the principles and hooks that fit your project, and sets them up for you. No plugin store, no config wizard.
Most AI-coding coordination products want to host your context, charge per seat, or lock you into their dashboard. mclaude and claude-code-config sit in your repo as plain files. No account. No server required. No subscription.
If your company already uses Claude Code, the coordination problem is already there — it’s just being paid as human tax. Teams fight merge conflicts, re-discover dead ends, duplicate investigations, and lose context every Friday. This gives that tax back as structured files in git.
Read the full README →Use it, fork it, embed it in proprietary stacks. No per-seat pricing, no call for a quote.
Python 3.9+ and a filesystem. CI runners, airgapped machines, emergency SSH — all supported.
.claude/ is text. It diffs, reviews, and merges like any other code. Nothing to self-host unless you want to.
Hub offline? Falls back to local files. Team doesn’t want messages? Use locks alone. Nothing hard-fails.
20+ native tools (mclaude_lock_claim, mclaude_handoff_latest…) so Claude Code calls them directly — no Bash parsing.
mclaude decides who does what. claude-code-config is the rulebook: 23 architectural principles, 14 safety hooks, 19 skills. Parallel sessions share a filesystem — they need guards that run whether the agent remembers the rule or not.
Start with pip install mclaude
and the built-in demo. Add claude-code-config for principles and safety. Ship both to your team — same repo, zero infrastructure.
MIT licensed · 190+ tests · zero core deps · contributions welcome