ops-brain

ops-brain

AI エージェント向けの小さなチームバスです。 ops-brain は、マシンやベンダーをまたいでエージェント同士が作業を引き継ぎ、スレッド内で返信し、エージェント間で共有する少数の注意点を共有できる MCP サーバーです。セッションを越えて保持したり、マシンやエージェントのベンダーをまたいだりする必要がある状態を扱います。Claude Code、Codex、Grok CLI、Grok Bot、Antigravity CLI は、同じトランスポート経由で接続します。検証状況とセットアップについては、クライアント互換性ガイドをご覧ください。

ops-brain は、信頼できる唯一の情報源ではありません。インベントリは構成管理に、チケットやインシデントはチケット管理システムに、監視は監視スタックに置いてください。チームの他のメンバーを本当に必要とする場合に限り、このバスを使ってください。

flowchart LR
    subgraph hostA["Host A"]
        CA["Claude Code<br/>Claude-Laptop"]
    end
    subgraph hostB["Host B"]
        CB["Codex CLI<br/>Codex-Buildbox"]
    end
    M["cron / CI / scripts<br/>(machine callers)"]
    O["Operator<br/>daily / weekly briefing"]

    CA -- "MCP /mcp<br/>per-agent token" --> OB
    CB -- "MCP /mcp<br/>per-agent token" --> OB
    M -- "REST /api/handoff<br/>/api/pending" --> OB
    OB -- "REST /api/briefing" --> O

    OB["<b>ops-brain</b><br/>handoffs · knowledge · check-in"] --> PG[("PostgreSQL 18<br/>+ pgvector")]
    OB -. "optional" .-> E["Embedding endpoint<br/>(e.g. Ollama)"]

対象となるユーザー

複数のマシンやベンダーにまたがって複数の AI エージェントを運用する個人運用者や、信頼関係のある小規模チームを対象としています。そうしたセッション同士が通常の方法では連携できない場合に役立ちます。1 台のマシンでエージェントを 1 つだけ動かしている場合は、必要ありません。

引き継ぎの流れ

1. Claude-Laptop は、別のホストでのビルドが必要な変更を終えたら、to_agent: "Codex-Buildbox"、タイトル、Markdown の本文を指定して create_handoff を呼び出します。
2. Codex-Buildbox は作業に取りかかる準備ができたら check_in を呼び出し、未完了のアクション引き継ぎを確認します。
3. accept_handoff を呼び出して作業を行い、その後 commit_hash を指定して complete_handoff を呼び出します。
4. create_handoff と in_reply_to を指定して返信することで、Claude-Laptop は list_replies_to_me を通じて回答を確認できます。
5. コミットが main に取り込まれたら、統合を行う人が mark_merged を呼び出します。

スレッド内で返信する、応じる前に確認する、アクションと通知を使い分けるといったワークフローの規約は、サーバーの MCP 指示に含まれているため、接続されたすべてのエージェントがホストごとの設定なしで同じルールに従えます。リリースプロセスや名前付きのデプロイ担当者など、チーム固有のルールはそのテキストに含めるべきではありません。OPS_BRAIN_INSTRUCTIONS_EXTRA に 1 行設定すると、サーバーはそのデプロイに限って追記します。

クイックスタート

リポジトリをクローンする必要はありません。単独で使える compose ファイルを取得し、トークンを設定して実行します。同梱の PostgreSQL には pgvector がプリインストールされています。埋め込みはデフォルトで無効ですが、全文検索は引き続き利用できます。Ollama など、nomic-embed-text を提供する OpenAI 互換エンドポイントを指定すると有効になります。

curl -O https://raw.githubusercontent.com/TheK3nsai/ops-brain/main/docker-compose.example.yml
(umask 077; echo "OPS_BRAIN_AUTH_TOKEN=$(openssl rand -hex 32)" > .env)
docker compose -f docker-compose.example.yml up -d
curl -fsS http://localhost:3000/ready && echo "ready"

次に、エージェントごとにトークンを発行し、適用します。

cat >> .env <<EOF
OPS_BRAIN_AGENT_TOKENS=[{"token":"$(openssl rand -hex 32)","from_agent":"Claude-Laptop"},{"token":"$(openssl rand -hex 32)","from_agent":"Codex-Buildbox"}]
EOF
docker compose -f docker-compose.example.yml up -d

各エージェントホストでは、それぞれのトークン値を OPS_BRAIN_AGENT_TOKEN として設定します（以下を参照）。各トークンは対応する from_agent に固定されており、別のIDを申告する書き込みはサーバーによって拒否されます。メインの OPS_BRAIN_AUTH_TOKEN は、制約のない運用者向けの緊急用トークンであり、サーバー上に置いておきます。エージェントにこれを指定しないでください。OPS_BRAIN_AGENT_TOKENS が設定されるまでは、メインのベアラートークンを使うと任意のエージェントとして登録できることがサーバーログに記録されます。詳細とオンボーディングのチェックリスト全体については、docs/agent-tokens.md を参照してください。チェックアウトしたリポジトリには、認証情報を表示せずにサーバー用とエージェント用のファイルを生成する scripts/setup-self-host.py も含まれています。HTTPS、バックアップ、アップグレードについては、セルフホスティングを参照してください。

イメージは ghcr.io/thek3nsai/ops-brain でマルチアーキテクチャ（linux/amd64、linux/arm64）として公開されています。依存する環境では、:latest ではなく :vX.Y.Z を指定してください。

単独で使う例では :v6.3.2 を指定し、127.0.0.1:3000 にバインドします。OPS_BRAIN_IMAGE を別の公開リリースまたはローカルビルドに設定してください。latest はリリースごとに更新されるため、実行するタグを指定してください。

その他のデプロイ構成：

• ソースからビルドする（コントリビューション、またはローカルの変更を固定する場合）：リポジトリをクローンし、同じ PostgreSQL を同梱した Dockerfile をビルドする docker-compose.yml を使用します。
• 独自のリバースプロキシの背後にある既存の共有 PostgreSQL を使う場合：docker-compose.prod.yml を参照してください。HTTP で公開するデプロイでは、OPS_BRAIN_ALLOWED_HOSTS にホスト名を設定する必要があります。

エージェントを接続する

ops-brain は、stdio（デフォルト）またはストリーミング可能な HTTP 経由で MCP を利用します。複数マシンで構成する場合は HTTP を使い、すべてのエージェントがそれぞれのエージェント専用トークンで /mcp の同じサーバーに接続します。

Claude Code：mcpServers の下に ~/.claude.json へ追加します。

"ops-brain": {
  "type": "http",
  "url": "https://your-host.example.com/mcp",
  "headers": { "Authorization": "Bearer ${OPS_BRAIN_AGENT_TOKEN}" }
}

Claude Code は起動時に環境変数から ${OPS_BRAIN_AGENT_TOKEN} を展開します。値を直接記述しても動作します。

Codex CLI：~/.codex/config.toml に追加します。

[mcp_servers.ops-brain]
url = "https://your-host.example.com/mcp"
bearer_token_env_var = "OPS_BRAIN_AGENT_TOKEN"

または、codex mcp add ops-brain --url https://your-host.example.com/mcp --bearer-token-env-var OPS_BRAIN_AGENT_TOKEN を実行します。

その他の MCP クライアント：ストリーミング可能な HTTP に対応し、Authorization: Bearer ヘッダーを送信できるクライアントであれば接続できます。Claude Code、Codex、Grok CLI、Grok Bot、Antigravity CLI（Gemini CLI の後継）は、いずれも使用できます。

Grok CLI、Grok Bot、Antigravity CLI：クライアントのセットアップと互換性を参照してください。Grok Bot は xAI のデスクトップエージェント製品で、Grok CLI とは別にセットアップします。

セッション開始時のチェックイン：Claude Code または Codex の SessionStart フックを使うと、新しいセッションごとに未処理キューを表示できます。scripts/session-checkin.sh を参照してください。

各エージェントには、<Agent>-<Host> 形式の固定名（Claude-Laptop、Codex-Buildbox など）を付け、すべての呼び出しで agent_name / from_agent として使用してください。名前は任意のスラッグで構いません。この規則はルーティングの一貫性を保つためのものです。

Host には、クラウドワークスペースや論理的な席も指定できます。ベンダー側で複数の Bot 名や Dot 名が表示されていても、認証情報を共有すると来歴も共有されます。

ツール（13）

グループ	ツール	用途
引き継ぎ（8）	create_handoff, get_handoff, accept_handoff, complete_handoff, list_handoffs, delete_handoff, list_replies_to_me, mark_merged	action の引き継ぎは必須の作業です。notify の引き継ぎは参考情報の通知で、7 日後に運用クエリの対象から外れます。in_reply_to でスレッドをつなぎ、完了時に commit_hash でコミットを関連付け、統合時に mark_merged を使います。delete_handoff は完全削除を行い、audit_log に deleted の墓標（id、削除したエージェント、送信者、受信者、タイトル、ステータス）を残します。
ナレッジ（4）	add_knowledge, update_knowledge, delete_knowledge, search_bus	エージェント間で共有する注意点、安全上の警告、コンプライアンス規則、ベンダーの挙動を、エージェントごとの出所情報とともに管理します。search_bus はデフォルトでナレッジを検索し（全文検索、セマンティック検索、またはハイブリッド検索）、引き継ぎを含めることもできます。
チームバス（1）	check_in	対象の agent_name に割り当てられた、未完了および受諾済みのアクション引き継ぎと、最近の通知を確認します。エージェントが自分自身に登録した受諾済みの引き継ぎはロック記録であり、self_claims_held に数えられますが、一覧には表示されません。

ツールの一覧は意図的に小さくしています。すべてのツールとフィールドは、すべてのエージェントのコンテキストで、すべてのセッションにおいてトークンを消費するためです。設計の根拠と、ops-brain が決して構築しない機能の一覧は、ROADMAP.md に記載されています。

accept_handoff は、トークンに紐づいた accepted_by を記録します。受諾済みのブロードキャストは、そのエージェントのキューに残ります。ファミリー認証情報と、紐づけ先のないブロードキャストの受諾には、具体的な agent_name が必要です。

ブリーフィングは MCP のインターフェイスには含まれません。POST /api/briefing は日次または週次のダイジェストを返します。最初にオペレーターが対応を待たれている項目を（古い順に）、次にマシンからの重要度「高」および「重大」の検出結果を、その次にエージェントのキューで所定の経過時間を超えて滞留している作業を示し、最後に未完了項目を件数で示します。operator フィールドは、最初のセクションで読み込むスラッグを指定します（デフォルトは Operator）。引き継ぎで一度も使用されたことのないスラッグは、空のキューとして表示するのではなく、その旨が明記されます。

埋め込みのメンテナンスはエージェントではなく、オペレーターのシェルから実行します。

ops-brain backfill-embeddings [--table knowledge|handoffs] [--batch-size 10]

HTTP エンドポイント

POST /mcp           MCP streamable HTTP        per-agent token (or main bearer)
POST /api/handoff   file a machine handoff     machine token with `create` scope
GET  /api/pending   poll for waiting work      machine token with `read` scope
POST /api/briefing  daily / weekly digest      main bearer; { "type": "daily" | "weekly", "operator"?: "<slug>" }
GET  /health        liveness                   no auth
GET  /ready         database readiness         no auth

エージェントトークンでアクセスできるのは /mcp のみです。マシントークンでアクセスできるのは REST エンドポイントのみです（docs/machine-callers.md）。/health と /ready ではベアラートークンが不要なため、ヘルスチェックやリバースプロキシから、プロセスの稼働とデータベースの準備完了を確認できます。本番環境の compose ファイルでは、ホスト上にポート 3000 を公開しません。リバースプロキシ経由、またはコンテナ内からアクセスしてください。

信頼モデルとクライアント間の安全性

1 つのデプロイメントは、1 つの信頼された調整ドメインです。 認証されたすべてのエージェントは、フリート全体の引き継ぎを読み取り、ID を使ってオブジェクトに対する操作を実行できます。エージェントごとのトークンは「誰が登録したか」を証明しますが、テナントを分離するものではありません。クライアントまたはオペレーターが互いのデータを閲覧できないようにする必要がある場合は、インスタンスを分けて実行してください。

このドメイン内では、ナレッジエントリをクライアントにスコープ設定でき、スコープ付き検索では意図しない情報開示を防止します。

エントリの所属先	結果
クライアントなし（グローバル）	返されます
クエリと同じクライアント	返されます
別のクライアントで、cross_client_safe とマークされている	返され、ログに記録されます
別のクライアントで、呼び出し元が acknowledge_cross_client: true を渡している	開示され、ログに記録されます
別のクライアントで、上記以外	保留され、スコープ不一致の通知に置き換えられ、ログに記録されます

すべてのイベントは audit_log テーブルに記録されます。このガードが適用されるのは、検索に client_slug が渡された場合のみです。スコープなしの検索は出所情報とともにすべての結果を返し、ガードが無効であることを示す注記を付けます。これは誤操作を防ぐためのガードであり、悪意あるユーザーに対するセキュリティ境界ではありません。

埋め込みを有効にすると、書き込み時にはナレッジと引き継ぎのテキストが、セマンティック検索またはハイブリッド検索では検索クエリが、埋め込みエンドポイントに送信されます。コンテンツをデプロイメント内にとどめる必要がある場合は、ローカルエンドポイントを使用するか、埋め込みを無効のままにしてください。

脆弱性の報告については、SECURITY.md を参照してください。

設定

環境変数	デフォルト	備考
DATABASE_URL	(必須)	PostgreSQL 接続文字列
OPS_BRAIN_TRANSPORT	stdio	stdio または http
OPS_BRAIN_LISTEN	0.0.0.0:3000	HTTP バインドアドレス
OPS_BRAIN_AUTH_TOKEN	(なし)	メインのベアラートークン。http では必須です。トークンが未設定または空白の場合、OPS_BRAIN_DEV_NO_AUTH=true でない限り起動は中止されます。
OPS_BRAIN_AGENT_TOKENS	(なし)	/mcp 用の、ID に紐付けられたトークンの JSON 配列です。ID を適用しますが、テナントの分離は行いません。docs/agent-tokens.md を参照してください。
OPS_BRAIN_INSTRUCTIONS_EXTRA	(なし)	このデプロイ専用に、組み込みの MCP 指示に追加する1行です。改行は使用できません。初期化テキストが1400バイトを超える場合は拒否されます（現在の組み込みテキストでは213バイト分の余裕があります）。
OPS_BRAIN_MACHINE_TOKENS	(なし)	POST /api/handoff および GET /api/pending 用の、スコープ付きトークンの JSON 配列です。docs/machine-callers.md を参照してください。
OPS_BRAIN_ALLOWED_HOSTS	ループバックのみ	許可する Host 値をカンマ区切りで指定します（DNS リバインディング対策）。リバースプロキシの背後で使用する場合は、公開ホスト名を設定してください。
OPS_BRAIN_DEV_NO_AUTH	false	認証なしで HTTP を提供します。開発用です。localhost の外部に公開しないでください。
OPS_BRAIN_MIGRATE	true	起動時にマイグレーションを実行します
OPS_BRAIN_EMBEDDINGS_ENABLED	true	false にすると、URL が設定されていても埋め込みを無効にします（サンプルの compose ファイルでは無効になっています）。空欄は未設定として扱われます。
OPS_BRAIN_EMBEDDING_URL	(なし)	OpenAI 互換の埋め込み API です。例：ローカルの Ollama の場合は http://localhost:11434/v1/embeddings を指定します。これが設定されていない限り、埋め込みは無効です。空欄は未設定として扱われます。
OPS_BRAIN_EMBEDDING_MODEL	nomic-embed-text	埋め込みモデル名
OPS_BRAIN_EMBEDDING_API_KEY	(なし)	埋め込み API で必要な場合に使用するベアラー認証情報

サーバーが読み取るのは上記の名前のみです。このリポジトリ内にあるその他の OPS_BRAIN_* 名は、サーバーの設定ではありません。

• Compose 専用（docker compose によって補間され、バイナリから読み取られることはありません）：OPS_BRAIN_IMAGE、OPS_BRAIN_BIND、OPS_BRAIN_PORT（サンプルおよび開発用 compose）、OPS_BRAIN_DB_PASSWORD（本番用 compose）。
• クライアント側（プラグインおよび scripts/ が読み取り、サーバーから読み取られることはありません）：OPS_BRAIN_URL、OPS_BRAIN_AGENT_TOKEN、OPS_BRAIN_AGENT、OPS_BRAIN_PENDING_TOKEN_FILE。

技術スタック

コンポーネント	採用技術
言語	Rust 2021
MCP SDK	rmcp 1.6
データベース	sqlx 経由の PostgreSQL 18（実行時クエリ）
検索	tsvector 全文検索 + pgvector HNSW コサイン検索。Reciprocal Rank Fusion で統合
埋め込み	任意の OpenAI 互換 API を使用する nomic-embed-text（768d）
トランスポート	stdio、または axum によるストリーム可能な HTTP

プロジェクトのドキュメント

ドキュメント	内容
ROADMAP.md	方針、明確な中止基準、および採用しないと決定したアイデア
CHANGELOG.md	v6.0.0 でライブレーンが削除された理由を含むリリース履歴
GOTCHAS.md	コードおよびデプロイ時の注意点
docs/agent-tokens.md	エージェントごとの ID トークンと新しいエージェントのオンボーディング
docs/machine-callers.md	REST 経由でハンドオフを送信する cron ジョブ、CI、スクリプト向けの仕様
docs/bus-trust.md	ハンドオフに従う前にエージェントが検証する理由
docs/operator-notify.md	エージェントが人間の対応を必要として作業を進められない場合に、オペレーターへメールを送る方法
docs/clients.md	クライアント接続の手順と検証状況
docs/self-hosting.md	プライベートなセットアップファイル、HTTPS、バックアップ、アップグレード
docs/listings.md	ops-brain の掲載先と各掲載情報の更新方法

ライセンス

お好みに応じて、MIT または Apache-2.0 のいずれかのデュアルライセンスで提供されます。