# octopus-blackboard

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: octoryn
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/octoryn/octopus-blackboard
- Updated: 2026-07-15
- HTML: https://affpapa.org/en/nevibecode/mcp/octopus-blackboard

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `OCTOBOARD_AGENT`, `OCTOBOARD_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env OCTOBOARD_AGENT=<OCTOBOARD_AGENT> --env OCTOBOARD_DIR=<OCTOBOARD_DIR> --transport stdio octopus-blackboard -- npx -y octopus-blackboard
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add octopus-blackboard --env OCTOBOARD_AGENT=<OCTOBOARD_AGENT> --env OCTOBOARD_DIR=<OCTOBOARD_DIR> -- npx -y octopus-blackboard
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "octopus-blackboard": {
            "command": "npx",
            "args": [
                "-y",
                "octopus-blackboard"
            ],
            "env": {
                "OCTOBOARD_AGENT": "<OCTOBOARD_AGENT>",
                "OCTOBOARD_DIR": "<OCTOBOARD_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e OCTOBOARD_AGENT=<OCTOBOARD_AGENT> -e OCTOBOARD_DIR=<OCTOBOARD_DIR> octopus-blackboard npx -y octopus-blackboard
```
Replace <…> with your own values

## When to use it
- 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
- Call `board_status` and tell me who is on the board right now
- Write to the board: Claude is refactoring the auth middleware
- Claim `trust-layer-policy-schema` and warn me if another agent already holds it

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md