Getting Started

Getting started

Goal of this page: a working board, an agent connected to it, and proof that the connection is real. About ten minutes.

You need uv (a Python package manager) and Python 3.12. Nothing else — the core has no third-party dependencies.

---

1. Install

git clone https://github.com/TapanManu/blackboard.git
cd blackboard
uv venv --python 3.12 && uv pip install -e '.[dev,mcp]'
uv run pytest -q        # 120 tests, about 3 seconds

The mcp extra is not optional if an agent will connect to the board. Without it, serve --stdio exits with MCP transport needs the optional dep. MCP — the Model Context Protocol — is the vendor-neutral standard by which an AI agent connects to an external tool. Nothing here is specific to one model or one vendor.

2. Create a workspace and an access token

A workspace is one project or engagement, with its own database file.

uv run blackboard-mcp --workspace myproject init
uv run blackboard-mcp --workspace myproject grant --role planner --quiet

The second command prints an access token. Keep it out of any shared config file — use your client's variable substitution instead.

--workspace is a global flag: it goes before the subcommand, never after. grant --workspace myproject exits with an error.

3. Connect your agent

Whatever your client's configuration format, it needs the equivalent of:

Field	Value
command	the blackboard-mcp entry point — use the virtualenv's absolute path if the client does not start in this directory
args	--workspace <name> serve --stdio, in that order
environment	BLACKBOARD_TOKEN (from step 2) and BLACKBOARD_ROLE

The variable names are BLACKBOARD_TOKEN and BLACKBOARD_ROLE. Nothing reads BB_TOKEN.

For Claude Code, copy .mcp.json.example to .mcp.json in the repository and fill in the token.

4. Teach the agent the protocol — do not skip this

A board that is merely reachable gets used badly. Agents escalate every read to the full note and recreate exactly the context bloat the board exists to prevent, while still paying the standing cost of having the tools available. In that state you are worse off than with no board at all.

Copy or symlink these instruction files into wherever your client discovers them:

Instruction set	Covers	Install when
skills/blackboard/	the protocol: addresses, summary-first reads, write discipline	always
skills/blackboard-parallel/	fanning out to helper agents, background shells, monitors, lane naming	your client spawns helper agents or background work
skills/session-handoff/	parking a task and resuming it in a fresh session	sessions get stopped, cleared, or hit limits

If an adapter exists for your client under integrations/, apply it too. The adapter carries the deterministic plumbing — how that client injects the contract into every helper agent it spawns, and how it defines a worker whose tools are scoped to the board. Skills alone still work; the adapter makes coverage automatic rather than model-decided.

5. Verify

Three checks, cheapest first.

# a. the workspace exists and the server starts
uv run blackboard-mcp --workspace myproject status

# b. the transport handshakes and lists five tools
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  | BLACKBOARD_TOKEN=<token> uv run blackboard-mcp --workspace myproject serve --stdio | head -c 200

c. From inside the client, ask the agent to read the orientation address: get_state("bb://myproject/run/state/current").

Check (c) fails on a brand-new board, because nothing has been written yet. That is expected — and it is the first thing to fix. Seed one entry at that address describing the goal and the current state, or the resume path has nothing to resume from.

Housekeeping commands

These are command-line only. No agent can call them.

Command	What it does
init	create a workspace
grant	issue an access token for a role, scoped to topics
status / health	show what the board holds and whether it is sound
export / import	move a workspace between machines
vacuum	delete unreferenced stored files
destroy	delete a workspace

Before you set any of this up, one honest check

If your work has fewer than about five sub-tasks, fits in a single context window, or is a single session with no hand-off and no crash risk, skip all of it and just do the task. Limits explains where the break-even actually sits.