Shared Workspace MCP

Shared memory & verified handover for AI agents. Codex and Cowork pass work back and forth without losing the thread — and can't fake "done".

“Cairn” is the unofficial name for the Shared Workspace MCP (shared-workspace-mcp).

🔄 The gated pipeline

🏆 Earn the level

✨ What it does

Windows (PowerShell)

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/WhileTrueBlackObelizk/shared-workspace-mcp/main/install.ps1 | iex"

Linux (systemd user service)

curl -fsSL https://raw.githubusercontent.com/WhileTrueBlackObelizk/shared-workspace-mcp/main/install.sh | bash

Then point your MCP client at:

http://localhost:8765/sse

Claude Code can also spawn it over stdio:

claude mcp add --scope user shared-workspace -- python /path/to/shared-mcp/server.py --stdio

On Windows the installer wires up the Claude Desktop / Cowork config and removes the older duplicate local extension if present. Restart Claude, then ask Cowork for workspace_dump or gate_check. Liveness: GET http://localhost:8765/health.

The repository contains the MCP server and installer only. Your actual agent memory is local runtime data under:

~/.claude/shared-workspace/

That directory is not part of this repo and should not be committed. It may contain project names, handovers, file paths, decisions, and logs from your machine.

The hot workspace should stay small:

active_task
session_owner
context
current_plan
acceptance_criteria
last_output
next_steps
blockers
handover_notes
workspace_health

Long project notes belong in project files, docs, or namespaced project keys. workspace_dump prints hot keys in full, previews long cold keys, and points to workspace_read for the full value.

Compact state outside the prompt, pulled only when it matters:

workspace_dump
workspace_audit
workspace_maintain
mcp_doctor
get_recent_activity n=10
learning_search query="similar failure"
learning_context query="current task"
gate_check step=test root="C:\path\to\repo" source=cowork
gate_advance pipeline_id=my-task root="C:\path\to\repo" source=cowork
drift_report pipeline_id=my-task
goal_complete goal_id=my-task        # self-scores + levels up

Default pipeline: intake → plan → implement → test → review → handover. Advance with gate_advance (not manual edits); a blocked gate writes a lesson.

handover_takeover runs safe maintenance and a lightweight doctor summary before it returns context. It does not delete project knowledge. It only removes stale temporary JSON files and writes a small workspace_health key.

It reports attention when:

workspace_dump is too large
one hot key is too long
active context and current_plan mention different projects
current_plan is stale
old temporary files exist
many completed pipelines remain in the live store
more than one goal is active

Use workspace_audit to inspect the full report and workspace_maintain to run the same safe cleanup manually.

Use mcp_doctor when investigating runtime or process issues. It checks runtime/file drift, workspace hygiene, and duplicate server.py registrations, then returns recommended next actions. Many observed server processes are reported as an informational hint when they map to distinct clients; duplicate registrations remain the warning condition.

Takeovers include the lightweight doctor summary automatically. Call mcp_doctor directly when you also need the process probe.

Takeovers also include learning_context, an automatic relevance pass over stored lessons using the active task and current plan. Agents still can call learning_search, but routine starts do not depend on remembering to ask.

Writing active_task also records a task_start activity automatically, so the intake gate does not depend on a second manual log call.

• Binds 127.0.0.1 only · file paths must stay under your home · run_check runs fixed presets, never arbitrary shell.

• Storage: UTF-8 JSON under ~/.claude/shared-workspace/. No hosted DB, no paid service.

• Deep dives: ARCHITECTURE.md · handover-protocol.md · SECURITY.md · agent rules in AGENTS.md.