mclaude

Multi-session collaboration for Claude Code and other AI coding agents. mclaude is a file-based coordination layer for the case where two Claude chats are working on the same project — or two teammates each running Claude Code, or one person switching between laptops. Zero core dependencies, 166 tests, MIT-licensed.

The problem it addresses

You ask Claude to fix a bug. Three minutes later your teammate on a different laptop asks their Claude to do the same thing. Neither knows the other exists. Both PRs open. Both delete the same function. Merge conflict, test failure, and the decisions live in two chat histories nobody else can read.

The seven layers

Each solves one problem and is independently usable:

1. Work locks — atomic file creation (O_CREAT | O_EXCL) under .claude/locks/active-work/. Heartbeat refreshed every 30 seconds; stale after 3 minutes. A second session trying to claim the same slug sees who's holding it, what they're working on, since when, and which files are touched.
2. Handoffs — each session writes a markdown handoff file YYYY-MM-DD_HH-MM_<session-id-prefix>_<slug>.md on lock release.
3. Memory graph — shared knowledge that survives across sessions.
4. Messaging (mclaude mail) — questions and answers between sessions.
5. Hub server — optional network coordination point.
6. Bridge — connector for cross-machine setups.
7. Voice I/O — audio extension.

All artifacts are plain markdown and JSON in .claude/, so the project state is human-readable and git-trackable.

Demo

mclaude demo --no-pause spins up a temp directory, walks two simulated sessions (ani and vasya) through six coordination layers, and prints a Mermaid sequence diagram of what happened. About 30 seconds. The diagram pastes directly into GitHub or Habr posts. scripts/mclaude_watch.py runs in a second terminal as a live observer for the demo.

Companion projects

The README pairs mclaude (the runtime — who does what, when) with claude-code-config (the rulebook — 23 architectural principles, 14 safety hooks, the proof-verify skill). Parallel sessions specifically benefit from destructive-command-guard, git-destructive-guard, and git-auto-backup — they protect shared state while mclaude coordinates access.

External task-tracker integration (Linear, Jira, GitHub, Vikunja) is left to ~200-line example scripts in examples/integrations/ for the consuming team to fork. mclaude itself never calls a tracker.

Where it sits

The architecture is the file-based memory pattern jxnl describes in jxnl-codex-maxxing taken several layers further. Where jxnl's vault is the LLM's notebook, mclaude is closer to a coordination kernel — atomic locks, attributed handoffs, a memory shelf, and a mail layer — for the case where multiple agents share that notebook.

Adjacent to agent-principal-agent-problem (Crawshaw on how agents collapse the contributor/reviewer effort signal) and matryoshka-isolation (sandboxing at the process layer). mclaude solves the orthogonal problem — once you have a sandboxed agent that won't burn down your repo, how do two of them coordinate without stepping on each other?

Repo: github.com/AnastasiyaW/mclaude — Python, MIT-licensed, single-author project (6 stars at time of ingest)

Source: mclaude-readme