octopus-blackboard

Octopus Blackboard

AI コーディングエージェントのための共有メモリおよび調整レイヤー。

エージェントに必要なのは、新たな上司ではありません。共有の掲示板です。

簡体字中国語

Octopus Core の一部 — 統制された AI のためのオープンインフラストラクチャスタックです。 エージェントのライフサイクルに沿って、各リポジトリが担う役割は 1 つです：Scout · Observe · Experience · Blackboard · Workstate · Runtime · Replay — すべての段階を Inspect が統制します。スタック全体は、1 つのルートプリミティブ、すなわち、すべての構築の基盤となる標準的で改ざんを検知できる最小単位、Evidence の上に成り立っています。

このリポジトリ — Blackboard · 調整： コーディングエージェントのための共有認知。

---

Claude Code、Codex、Gemini CLI、Cursor、そしてローカルのエージェントは、すべて同じリポジトリで作業します。しかし、互いの状況は見えません。あるエージェントが認証をリファクタリングしている間に、別のエージェントが同じファイルを書き換えてしまいます。コンテキストは CLI ごとに散在しています。何が起きたのかを再現できる人はいません。

Octopus Blackboard はオーケストレーターではありません。 エージェントのスケジュール設定や起動を行ったり、エージェントに代わって何かを決定したりはしません。次の 6 つの質問に答える、受動的でローカルファーストな共有メモリです。

Who is working on what      →  agents, tasks, claims
What changed                →  files_changed
What was decided            →  decisions
What evidence exists        →  evidence
What risks are open         →  risks
What was left for whom       →  messages, handoffs

エージェントに必要なのは、ボードを読み、ボードに書き込み、メッセージを残し、証拠を添付することだけです。それがすべての取り決めです。

導入の理由

企業が主に懸念しているのは、エージェントの知能が不十分なことではありません。懸念しているのは次の点です。

• 複数の AI ツールが同じコードを同時に編集する
• コンテキストが異なる CLI に散在している
• 共有メモリも監査も引き継ぎもない
• 競合を認識する仕組みも、再現する方法もない

この掲示板は、こうした問題を一気に解決します。すべての書き込みは、追記専用の timeline に改ざんを検知できるハッシュチェーン付きエントリーとして追加されるため、履歴全体を監査して再現できます。また、後から以前のエントリーを編集すると、検証に失敗します。

2 分で始める

Blackboard は Octopus スタックを始める最も簡単な方法です。オーケストレーターは不要で、Claude Code と Cursor だけで今すぐ使える、純粋な調整用メモリです。1 つのコマンドですべてをセットアップできます。

npx octopus-blackboard quickstart

このコマンド 1 つで、ローカルボード（.octoboard/）がなければ作成し、MCP クライアントを自動検出し（.claude/ → Claude Code、.cursor/ → Cursor、それ以外の場合は汎用スニペット）、そのクライアント用の正確な貼り付け可能な設定を表示して、書き込みと読み取りを 1 回ずつ行ってボードの動作を確認します。

あとは次の手順を実行するだけです。

1. 表示された設定ブロックを、指定されたファイルに貼り付けます。
2. MCP クライアントを再読み込みします（再起動するか、プロジェクトを開き直します）。
3. これで完了です。 エージェントに board_status、続けて board_note "hello" を呼び出すよう依頼します。これが、改ざんを検知できる共有タイムラインでの最初のボード操作です。

quickstart は何度実行しても安全です。既存のボードやその履歴を上書きすることはありません。まず調整レイヤーを導入するという考え方を初めて知りましたか？まず Blackboard を導入する理由をご覧ください。

インストール

npm install
npm run build      # compiles to dist/

Node ≥ 22 が必要です。ボードは .octoboard/ 内の単一の SQLite ファイルで、作業ディレクトリから上位へたどって検出されます（.git と同様です）。

動作例

examples/two-agents.sh では、代表的なシナリオを実行します。同じリポジトリで Claude Code と Codex が1つのボードを共有し、主張の競合、同じファイルでのリアルタイムな衝突、意思決定、クレジットの記録、もう一方のエージェントの受信箱に届く引き継ぎ、AI レビュー、人間の承認を必要とする CI ゲート（ブロック → 通過）、説明責任のスコアカード、blame→ナラティブ、セッション署名付きの検証済みハッシュチェーンを体験できます。空のディレクトリで実行してください。

bash examples/two-agents.sh          # needs `octoboard` on PATH

CLI

octoboard init                                   # create .octoboard/ here
octoboard status                                 # who's on the board, right now

octoboard note "Codex is refactoring auth middleware"
octoboard claim trust-layer-policy-schema        # claim work; warns on conflict
octoboard message claude "Review policy edge cases before merge"
octoboard decision "Use hash-chain audit log" --why "tamper-evidence"
octoboard risk "Migration may break audit replay" --severity high
octoboard file src/auth.ts --change modified --task trust-layer-policy-schema
octoboard handoff claude "Tests pass except policy replay" --task trust-layer-policy-schema

octoboard timeline                               # the full hash-chained history
octoboard verify                                 # confirm the chain is intact

ID は --as <agent> または OCTOBOARD_AGENT 環境変数で設定します。特定のボードを指定するには --board <dir> または OCTOBOARD_DIR を使います。

競合の把握

ボードは処理をブロックせず、競合を表面化させます。2つのエージェントが同じキーを主張した場合、または同じタスクのファイルを変更した場合、両方の書き込みが記録され、2番目のエージェントに警告が表示されます。

⚠ CONFLICT: "trust-layer-policy-schema" is also held by codex. Both claims recorded.

AI のクレジット記録と共有開発メモリ

Git には、コミットをプッシュした人は記録されます。しかし、どの AI エージェントが、どのセッションで、どのマシン上でコードを作成したのか、別の AI がレビューしたのか、人間が承認したのかは記録されません。AI ネイティブな開発が一般的になるにつれ、説明責任の対象は Git の作成者情報だけにとどまらなくする必要があります。

blackboard は Git の上にクレジット記録レイヤーを追加します。履歴を書き換えることはありません。コードの信頼できる情報源は引き続き Git であり、クレジット記録の信頼できる情報源が blackboard になります。

セッション

セッションはエージェントの1回の連続した実行であり、クレジット記録の基点となる単位です。セッションを開始すると、それ以降のすべての書き込みがセッションに紐づけられます（アクティブなセッションはエージェントごとに CLI の呼び出しをまたいで保持されます）。

export OCTOBOARD_AGENT=claude OCTOBOARD_PROVIDER=anthropic \
       OCTOBOARD_MODEL=claude-opus-4-8 OCTOBOARD_CLI=claude-code

blackboard session start --label "auth work"   # captures machine, branch, repo
blackboard claim policy-engine
blackboard file src/policy.ts --change modified
# ... make a git commit ...
blackboard link HEAD                            # attribute the commit's files
blackboard session stop

ID はプロバイダーに完全に依存しません。--provider、--model、--cli、または対応する OCTOBOARD_* 環境変数を使います。特定のベンダーを前提とせず、あらゆる AI CLI（ローカルまたはクラウド）が自身を登録できます。

コミットの紐づけ

blackboard link <rev> はコミットで変更されたファイルを（Git 経由で）読み取り、アクティブなセッションに対してファイルごとに1件のクレジット記録を保存します。必要に応じて、refs/notes/blackboard に追記専用の git notes エントリーも書き込みます。

blackboard link HEAD --note
blackboard attribute <sha> --file src/x.ts --actor human --name Ran  # manual

レビュー

blackboard review HEAD --by ai   --name codex --outcome approved --note "tests pass"
blackboard review HEAD --by human --name Ran   --outcome approved

共有メモリの検索

blackboard who src/auth.ts             # git authors + AI sessions that touched it
blackboard who src/auth.ts --line 42   # which session introduced this line
blackboard explain HEAD                # attribution + reviews + related decisions
blackboard commits claude-code         # which commits came from an AI / CLI
blackboard unreviewed                  # AI commits never reviewed by a human
blackboard joint claude codex          # files modified by BOTH agents
blackboard timeline --session <id>     # per-session HH:MM timeline

explain の例：

commit 5fa3095…  Human Dev <[email protected]>  add auth
  produced by:
    ai claude [claude-opus-4-8] — src/auth.ts
  reviews:
    human Ran: approved
  git note: blackboard: produced by claude-code (claude-opus-4-8), session 75b2b7e7…

すべてのクレジット記録、レビュー、セッション、意思決定も、ハッシュチェーン化された timeline に記録されます。そのため、説明責任に関する履歴全体は改ざんを検知でき、再生も可能です。blackboard と octoboard は同じコマンドです。

ガバナンスと説明責任のチェーン

クレジットを記録する目的は、何かを強制することです。作業からマージゲートまでの流れ：

agent work → commit attribution → export/import → CI check → human-review gate

CI ゲート（check）

クエリを強制力のあるゲートにします。読み取り専用で、合格／不合格を報告してゼロ以外の終了コードで終了します。対応を決めるのは CI システムです。blackboard が処理をブロックすることはありません。

# In CI, on a PR branch — fail the build if any AI commit isn't human-APPROVED
# (a rejected / changes-requested review does not clear the gate):
blackboard check --range origin/main..HEAD --require-human-review
echo $?   # 0 = pass, 1 = violations

blackboard check --verify-chain --require-attribution --range origin/main..HEAD
blackboard check            # default gate: verify chain + require human review

可搬性（export / import / trailers）

クレジット記録はローカル優先です。これらの機能により、git push 後もチームのボードや CI で利用できます。

blackboard export --range origin/main..HEAD --out attribution.json  # on the dev machine
blackboard import attribution.json                                   # on the team board / CI
blackboard trailers HEAD                                             # trailer lines for a commit message

import は冪等です（行 ID をキーにします）。バンドルにはクレジット記録、レビュー、セッション、および関連する意思決定が含まれます。

購読（watch）

読み取り／書き込み／購読／メッセージングの契約を完成させます。受動的にポーリングして結果を報告するだけで、作業をプッシュすることはありません。

blackboard watch --for claude     # only messages/handoffs/conflicts addressed to me
blackboard watch                  # the full stream
blackboard watch --once           # one-shot poll (for scripts)

署名付きセッション（sign / verify）

最小限のアイデンティティ（v0）：各セッションに Ed25519 のキーペアが割り当てられます（秘密鍵は gitignore された .octoboard/keys/ の下にローカル保存されます）。タイムラインの先頭に署名することで、verify は信頼された状態と、単にそう主張されているだけの状態を見分けられます。

blackboard sign        # sign the current head with the active session key
blackboard verify      # chain integrity + which sessions have signed, trusted/stale

セッションは session stop 時に先頭へ自動署名します。先頭への署名は、前の履歴が変更された時点で古くなります。そのため、署名自体は暗号学的に有効なままでも、改ざんが明らかになります。これはまだ完全な PKI ではありません（鍵の配布や失効には対応していません）。

CLI のトランスクリプトの取り込み

API を手動で呼び出す代わりに、CLI のセッショントランスクリプトからボードを作成できます。ファイルの編集、決定、メモがアクティブなセッションに反映されます。

blackboard ingest ~/.claude/transcript.jsonl --format claude-code
blackboard ingest session.jsonl --format codex        # also: gemini, grok
blackboard ingest events.json    --format generic --dry-run

claude-code／codex／gemini／grok は、保守的なツール使用の JSONL ヒューリスティックを使用します（file_path／notebook_path と、パッチ／書き込みツールの呼び出しからファイル編集を検出します）。generic は正規化されたスキーマを読み込みます。これはあらゆる CLI に対応する安定した統合方法です。

{ "events": [
  { "type": "file", "path": "src/auth.ts", "change": "modified" },
  { "type": "decision", "title": "use ed25519", "rationale": "small keys" },
  { "type": "note", "text": "left policy edge cases for review" }
] }

チームバックエンド

ボードはローカルファーストのまま、同期によってポータブルな帰属情報レコード（ボードのプライベートなハッシュチェーンは含みません）を共有ファイルまたは Postgres のチームストアに共有できます。

blackboard sync push --target /shared/team.json          # file (shared drive)
blackboard sync pull --target postgres://host/blackboard # team database (needs `pg`)

export はアクティブなセッションキーでバンドルに署名します。import はそれを検証し、import --require-signed は署名されていないバンドルや改ざんされたバンドルを拒否します。これにより、インポートされた帰属情報は ID の重複排除だけでなく、出所の真正性も備えます。

先頭を外部にアンカーすれば、改ざん検知機能を DB 内のチェーンよりも強化できます。

blackboard anchor --git-note              # record seq:hash on the commit (or --out file)
blackboard verify --against git-note      # prove history wasn't truncated/altered

稼働状況とコンプライアンス：

blackboard session heartbeat        # mark your session alive (active vs stale)
# `blackboard file ...` now warns if another LIVE session is editing the same file

blackboard prune --before 2026-01-01T00:00:00Z   # retention: drop old messages/
                                                 # evidence/file-changes (timeline kept)
blackboard redact 42 --reason PII                # hide a timeline entry's content

prune は追記専用のタイムライン（監査証跡）に触れることはありません。redact は、タイムラインのオーバーレイと、元のソース行（メッセージ本文、エビデンスのメモなど）の両方で内容を空にし、すべての読み取り経路から削除します。これにより、inbox／status／ダッシュボードから情報が漏れることを防ぎながら、ハッシュチェーンを有効なまま保ちます。これは暗号学的消去ではありません。チェーンの検証を維持するため、元の要約はタイムラインの行に残ります。そのため、破棄できる状態にしておく必要のある秘密情報は保存しないでください。データベースへの書き込み権限を持つ攻撃者に対する改ざん検知には、先頭のハッシュを外部（コミット、ログ、別のマシンなど）にアンカーしてください。末尾を確認できない場合、verify は unanchored 警告を表示します。

タスクとカンバン

タスクはカンバンカードです。番号、内容、担当者（エージェント／CLI）、プロジェクト、影響範囲、リスク、リアルタイムの進捗を記録します。**「エージェントへの通知」は受動的です。**タスクを割り当てると、「タスク #N を確認してください」というメッセージがそのエージェントの受信トレイに届き、エージェントはそれを読んで行動するかどうかを判断します。ボードが誰かを起動することはありません。

リアルタイムの blackboard serve ダッシュボード。読み取り専用で、自動更新されます。各カードには、タスク番号、進捗バー、担当者、アクティブなエージェントの数（⚡）、プロジェクト、リスクに応じた色の枠線が表示されます。

blackboard task add auth-mw --title "Refactor auth middleware" \
  --project octopus-api --impact "src/auth.ts, src/db.ts" --risk high
blackboard assign 1 claude       # → drops "please look at task #1 …" in claude's inbox
blackboard progress 1 40         # → moves #1 to in-progress, 40%
blackboard tasks                 # kanban view, grouped by status
blackboard task show 1           # full card: owner, project, impact, risk, files

読み取り専用の serve ダッシュボードでは、これらがリアルタイムのカンバンとして表示されます（ステータスごとの列。各カードには番号、タイトル、進捗バー、担当者、アクティブなエージェントの数、プロジェクト、リスクに応じた色の左枠が表示されます）。エージェントは MCP ツール board_task_define、board_assign、board_progress、board_tasks を通じて操作します。エージェントは作業中に board_progress を呼び出し、バーをリアルタイムで更新します。

可視性

blackboard report          # scorecard: review coverage %, AI/human ratio, per-agent
blackboard blame src/auth.ts 42   # trace a line → the session that wrote it, and its
                                  # other work, decisions, and handoffs (blame → narrative)
blackboard serve           # read-only local web dashboard (http://localhost:4319)

ダッシュボードは依存関係がなく（node:http）、厳密な読み取り専用（GET 以外のリクエストは拒否）で、自動更新されます。タイムライン、セッション、競合／帰属情報の状態、アカウンタビリティスコアカードをリアルタイムで表示します。

MCP サーバー — あらゆる CLI を接続

ブラックボードは標準の MCP over stdio で通信するため、MCP 対応クライアントならどれでも（Claude Code、Cursor、Codex、Gemini CLI、VS Code、Windsurf、…）ボードの読み書きができます。お使いのクライアントに合わせた設定を、ワンステップで生成できます。

blackboard mcp-config cursor        # → ~/.cursor/mcp.json block
blackboard mcp-config claude-code   # → project .mcp.json block
blackboard mcp-config codex         # → ~/.codex/config.toml (TOML)
blackboard mcp-config gemini        # → ~/.gemini/settings.json block
blackboard mcp-config vscode        # → .vscode/mcp.json (servers block)
blackboard mcp-config               # → generic mcpServers JSON (any client)

各コマンドは、設定を貼り付ける場所とすぐに使えるスニペットを出力します。例：

{
  "mcpServers": {
    "blackboard": {
      "command": "npx",
      "args": ["-y", "octopus-blackboard-mcp"],
      "env": { "OCTOBOARD_AGENT": "cursor" }
    }
  }
}

エージェントの識別情報は、デフォルトでクライアント名になります（そのため、Cursor は cursor として、Codex は codex として書き込みます）。--agent で上書きできます。作業ディレクトリ内の .octoboard/ からボードが自動検出されます。または、--dir で固定できます。同じ .octoboard/ を指定した 2 つの CLI は、1 つのボードを共有します。それがこの仕組みの目的です。

公開されるツール — 調整：board_status、board_timeline、board_note、board_claim、board_task_define、board_task、board_tasks、board_assign、board_progress、board_message、board_inbox、board_handoffs、board_decision、board_evidence、board_file_changed、board_risk、board_handoff、board_heartbeat、board_since；帰属情報：session_start、session_stop、board_link、board_attribute、board_review、board_who、board_explain、board_blame、board_unreviewed、board_report；ガバナンスとポータビリティ：board_check、board_export、board_import、board_trailers、board_sign、board_trust、board_prune、board_redact、board_ingest。各ツールは、呼び出しごとに実行主体の識別情報を上書きするための任意の agent 引数を受け付けます。

推奨される使い方：エージェントは作業を始める前に board_status を呼び出して、ほかの全員の作業状況を確認し、作業を進めながらボードに記録します。

データモデル

レイヤー	テーブル	目的
現在の参加者	agents、sessions	プロバイダーに依存しない識別情報、セッションのコンテキスト
進行中の作業	tasks、messages、handoffs	調整 — 依頼、メッセージ、引き継ぎ
成果物の作成者	attributions、reviews	AI／人間の帰属情報とレビューを、コミットに関連付けて記録
確定した事実	decisions、evidence、files_changed、risks、timeline	監査可能な共有メモリー

timeline は追記専用のハッシュチェーンであり、ほかのすべての書き込みも記録します。そのため、ボードと監査ログが食い違うことはありません。

アーキテクチャ

better-sqlite3 (local-first, default)
  + MCP server   (read / write board)
  + CLI          (octoboard ...)
  + hash-chain audit log (the timeline)
  + optional Postgres sync   (portable attribution records)
  + optional git / file watcher (planned)

ステータス

パブリックベータ（v0.3）。現在利用できる機能：ローカル SQLite ボード、CLI（octoboard／blackboard）、MCP サーバー、検証可能なハッシュチェーン型タイムライン、ファーストクラスのセッション、Git コミットに関連付けられたプロバイダーに依存しない AI／人間の帰属情報、レビュー、クエリレイヤー（who、explain、commits、unreviewed、joint）、読み取り専用の serve ダッシュボード、署名付きインポート／エクスポートバンドル、保持、編集、クイックスタート、MCP レジストリのメタデータ／公開ワークフロー。Git 統合は読み取り専用と追加的な git notes に限られ、履歴が書き換えられることはありません。チーム同期は、共有 JSON ファイルと、ポータブルな帰属情報レコード用の Postgres ターゲットに対応しています。ボードの非公開ハッシュチェーンは、設計上ローカルに保持されます。変更サブスクリプションと、より高度な Octopus のリポジトリ間ブリッジは、今後のロードマップ項目です。

ライセンス

Apache-2.0 © Octoryn。LICENSE をご覧ください。