octopus-blackboard — Claude Code MCP server: shared agent memory
A local board where several AI agents on one repo can see each other's tasks, edits and decisions. It records and exposes; it never orchestrates.
claude mcp add --env OCTOBOARD_AGENT=<OCTOBOARD_AGENT> --env OCTOBOARD_DIR=<OCTOBOARD_DIR> --transport stdio octopus-blackboard -- npx -y octopus-blackboardWhat octopus-blackboard does
Claude, Codex, Cursor and the rest all touch the same repository while being blind to one another. One refactors auth, another rewrites the same file. Blackboard gives them a shared surface: who holds which task, what changed, what was decided, which risks are open, what was left for whom. The contract is short — read the board, write the board, leave messages, attach evidence.
Every write appends a hash-chained entry to an append-only timeline. octoboard verify confirms the chain is intact, and editing an earlier entry after the fact breaks verification. The board never blocks anyone: if two agents claim the same key, both claims are recorded and the second agent gets a conflict warning. Storage is a single SQLite file under .octoboard/, found by walking up from your working directory the way .git is.
Building needs Node ≥ 22. The examples/two-agents.sh scenario expects octoboard on PATH; without it the script won't run. Identity comes from --as <agent> or the OCTOBOARD_AGENT variable, and a specific board from --board <dir> or OCTOBOARD_DIR.
For a first run, npx octopus-blackboard quickstart creates the board, detects your MCP client and prints a paste-ready config block. Running it again leaves an existing board and its history alone.
What it helps with
- check who already claimed a task before starting work
- catch a collision when two agents edit the same file
- record a decision together with the reason behind it
- hand off a task to another agent with its context
- confirm nobody rewrote the board history after the fact
Example prompts for the agent
- Call
board_statusand tell me who is on the board right now - Write to the board: Claude is refactoring the auth middleware
- Claim
trust-layer-policy-schemaand warn me if another agent already holds it
How to install octopus-blackboard
Platform CLI
claude mcp add --env OCTOBOARD_AGENT=<OCTOBOARD_AGENT> --env OCTOBOARD_DIR=<OCTOBOARD_DIR> --transport stdio octopus-blackboard -- npx -y octopus-blackboardReplace <…> with your own values
Platform CLI
codex mcp add octopus-blackboard --env OCTOBOARD_AGENT=<OCTOBOARD_AGENT> --env OCTOBOARD_DIR=<OCTOBOARD_DIR> -- npx -y octopus-blackboardReplace <…> with your own values
Config file
{
"mcpServers": {
"octopus-blackboard": {
"command": "npx",
"args": [
"-y",
"octopus-blackboard"
],
"env": {
"OCTOBOARD_AGENT": "<OCTOBOARD_AGENT>",
"OCTOBOARD_DIR": "<OCTOBOARD_DIR>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"octopus-blackboard": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"octopus-blackboard"
],
"env": {
"OCTOBOARD_AGENT": "<OCTOBOARD_AGENT>",
"OCTOBOARD_DIR": "<OCTOBOARD_DIR>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e OCTOBOARD_AGENT=<OCTOBOARD_AGENT> -e OCTOBOARD_DIR=<OCTOBOARD_DIR> octopus-blackboard npx -y octopus-blackboardReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about octopus-blackboard
How do I install octopus-blackboard in Claude Code?
Run claude mcp add octopus-blackboard -- npx -y octopus-blackboard. If you need environment variables, use the longer form: `claude mcp add --env OCTOBOARD_AGENT=<OCTOBOARD_AGENT> --env OCTOBOARD_DIR=<OCTOBOARD_DIR> --transport stdio octopus-blackboard -- npx -y octopus-blackboard`.
What does octopus-blackboard do?
It is passive local memory for several AI agents sharing one repository. It answers six questions: who is working on what, what changed, what was decided, what evidence exists, what risks are open, and what was left for whom.
How is octopus-blackboard different from an agent orchestrator?
It never schedules or triggers agents. The board only records and surfaces — conflicts are flagged rather than blocked, so both claims stay in the history and the second agent is warned.
