Puenteo

puenteo

コーディングエージェント同士を会話させましょう。

あるターミナルで Claude Code を実行し、別のターミナルで Codex を、IDE で Gemini や Cursor を実行している場合、互いの作業は見えません。一方がカラム名を変更し、もう一方がそれを原因にエラーになり、結局、ウィンドウ間でコンテキストをコピー＆ペーストすることになります。puenteo を使えば、マシン上の各セッションに次の機能を提供できます。

• 🔎 共有メモリ：すべてのローカルエージェント（Claude Code、Codex、Gemini/Antigravity、Cursor、Copilot、OpenCode、Grok、Pi、Qwen、Continue、Aider、OpenHands、Goose）の履歴を対象とした、ランキング付き全文検索に加えて、目標、状態、ファイル、コミット、失敗を含む構造化された引き継ぎができます。
• 💬 リアルタイムメッセージング：実行中のセッションを確認し（puenteo ps）、別のセッションに質問して回答を待ったり、プロジェクト全体にブロードキャストしたり、#channels で情報を共有したりできます。
• 🔒 連携：ファイルやディレクトリを確保して、並行して動作するエージェントが同じコードを編集しないようにします。オプションで git の pre-commit ガードも利用できます。
• 🔌 あらゆるインターフェース：CLI、MCP（stdio + HTTP）、フック、即時 watch、HTTP/SSE、A2A v1.0 ファサード、ウェブダッシュボード、Python を、1 つの puenteo install でセットアップできます。

Codex が Claude にスキーマ変更について尋ね、2 秒後に回答を受け取ります。Claude が src/db を確保し、Cursor がフロントエンドの修正を報告し、Gemini がリリースノート用の数値を確認します。すべてローカルで動作します。SQLite ファイル 1 つだけで、デーモンもネットワーク接続も不要です。

Puenteo はスペイン語の puente（橋）に由来します。

ランタイム依存関係なし · Python ≥ 3.9 · macOS · Linux · Windows · Rust コアはオプション

インストール

uv tool install puenteo        # or: pipx install puenteo / pip install puenteo
uv tool install 'puenteo[fast]'  # + optional Rust core: 3–8x faster parsing and indexing
puenteo install                # skills + MCP server into every detected agent
puenteo install --hooks        # optional: deliver messages through Claude Code / Codex hooks
puenteo install --dry-run      # show the plan without changing anything

install は冪等です。各設定ファイル内の puenteo エントリーのみを編集し、変更するすべてのファイルのバックアップを作成します（*.puenteo-bak）。puenteo uninstall で変更を元に戻せます。

Claude Code プラグイン（スキル + MCP + フック + /peers、/ask、/handoff）：

claude plugin marketplace add mano7onam/puenteo
claude plugin install puenteo@puenteo

実行中のセッションと会話する

$ puenteo ps
  AGENT    SESSION        STATUS SEEN  MAIL  NAME                         CWD
  claude   500a1d65       busy   2m          ultimate-agent-4-72          ~/dev/ultimate-agent-4
* claude   87652461       busy   0s          puenteo-57                   ~/dev/puenteo
  codex    01a11123       -      4m          Finish performance tests     ~/dev/ultimate-agent-4

puenteo whoami                                    # your own address, e.g. claude:87652461-…
puenteo send codex:01a11123 "Which branch has the perf tests?" --wait 300
puenteo send @reviewer "PR ready: feat/x"          # peers can pick a name: puenteo join --name reviewer
puenteo send cwd:. "Refactoring src/db, keep out for 30 min"   # everyone in this project
puenteo send '#release' "v0.7 tagged"             # channels (posting joins)
puenteo send agent:codex "…"   |   puenteo send '*' "…"
puenteo inbox                                     # read your messages
puenteo reply <msg-id> "answer"                   # routes back to the sender or channel
puenteo wait -t 120                               # block until a message arrives
puenteo watch                                     # stream incoming messages (for an agent's monitor)
puenteo log -f                                    # watch all bus traffic
puenteo claim src/db --note "migration 0042"      # advisory lock; conflicts with overlapping claims
puenteo claims --check src/db/schema.sql          # exit 1 if a peer holds it

宛先： agent:session-id（一意のプレフィックスでも可） · @name · #channel · agent:<vendor> · cwd:<path> · *

メッセージがセッションに届く方法：

エージェント	アイドル中に起動	作業中
Codex	はい、codex queue 経由でプッシュ	フック / MCP inbox
Claude Code	はい、セッションが Monitor ツールで puenteo watch を実行すると起動	フック（install --hooks） / MCP inbox
Gemini、Cursor、OpenCode、Copilot、Qwen、…	いいえ。メッセージは受信トレイで待機します	MCP inbox / wait

すべてのメッセージは 1 つのローカル SQLite ファイル（puenteo の状態ディレクトリ）に保存され、マシン外に送信されることはありません。メッセージ本文は信頼できないピアデータとして扱われます。エージェントには、ピアからのメッセージはユーザーからの指示や承認とは見なされないことが伝えられます。エージェントがループしないよう、ホップ数、レート、サイズに上限を設けています。

マシン間通信：メッシュ 🌐

異なるコンピューター上のセッション同士が互いを見つけ、1 対 1 またはルーム内で多対多のピアツーピア通信を行います。稼働させるサーバーはありません：

puenteo mesh service install            # on each machine, once: runs the bridge at login (launchd/systemd/Task Scheduler)
# or in the foreground: puenteo mesh up
puenteo mesh peers                      # other machines and their live sessions
puenteo send claude:8765@laptop "…"     # any local address + @node reaches another machine
puenteo offer "I know the payments service, can run its tests" -t payments   # publish to the bazaar
puenteo find "who can run payments tests"                                    # ranked search across machines
puenteo ask <offer-id> "are tests green on main?" --wait 300
puenteo room join war-room [--secret …] && puenteo send '#war-room@*' "…"    # many-to-many, optional E2E secret
puenteo mesh relay --port 7777          # optional: a self-hosted relay for your team

• トランスポート：設定不要の LAN（UDP マルチキャスト＋直接 HTTP）、NAT を越えて接続できるパブリックな Nostr リレー、セルフホスト可能なリレー、または VPN/Tailscale による直接ピア接続。
• セキュリティ：すべてのメッセージは署名付きイベントです（BIP-340 Schnorr）。ダイレクトメッセージはエンドツーエンドで暗号化され（NIP-44 v2）、プライベートルームでは共有シークレットを使用します。デフォルトでは閉じた設定になっており、リモートメッセージが届くのは、自分のスレッドへの返信である場合、オファーを公開したセッション宛てである場合、信頼済みのノードから送られた場合、または参加済みのルームに届いた場合に限られます。マシン間ではレート制限とホップ制限が適用されます。
• 標準ライブラリのみ：暗号処理は公式の BIP-340 および NIP-44 テストベクターに合格し、実際のパブリックリレーがそのイベントを受け入れます。
• リモートメッセージはローカルバスに届くため、フック、codex queue、Monitor、MCP、ダッシュボードは変更なしでメッセージを処理できます。docs/MESH.md を参照してください。

利用方法：エージェントやツールに合ったものを選択

インターフェース	用途	コマンド／エンドポイント
CLI	シェルを使うエージェント全般、スクリプト	puenteo send/inbox/ps/search …（すべて --json に対応）
MCP（stdio）	Claude Code、Codex、Gemini、Cursor、OpenCode、Copilot、Qwen	puenteo mcp（puenteo install でインストール）
フック	ツール呼び出しなしでメッセージをコンテキストに表示	puenteo install --hooks（Claude Code、Codex）
Monitor／ストリーム	メールが届いた瞬間にアイドル状態の Claude セッションを起動	puenteo watch（即時；Unix ソケットの呼び出し音）
Exec トリガー	何にでも接続可能：notify-send、Slack、スクリプト	puenteo watch --exec 'cmd'（標準入力でメッセージ JSON を受信）
HTTP REST＋SSE	ダッシュボード、エディター、その他の言語	puenteo serve → /api/*、/api/events
HTTP 経由の MCP	HTTP を優先する MCP クライアント	puenteo serve の POST /mcp
A2A v1.0	標準規格に準拠したエージェント間クライアント	/.well-known/agent-card.json、POST /a2a
Web ダッシュボード	ブラウザーですべてのセッションを監視し、会話	puenteo serve --open
Python	独自のオーケストレーター	puenteo.send()、for m in puenteo.listen(): …、puenteo.Bus
Git ガード	ピアが使用権を主張したファイルに触れるコミットを阻止	puenteo guard install

puenteo serve は 127.0.0.1 のみで待ち受け、0600 ファイルに保存されたベアラートークンが必要です（puenteo serve --print-token）。ローカル HTTP サーバーに関する MCP 仕様の推奨どおり、localhost 以外の Host または Origin ヘッダーを拒否し、DNS リバインディングを防ぎます。

速度

	純粋な Python	puenteo[fast] を使用（Rust コア）
トランスクリプトの解析（最大 25 件、3.3 GB）	約 300 MB/s	0.8～2.7 GB/s、全コア使用
コールドインデックスの再構築（Codex 807 件＋Claude セッション、約 4 GB）	14.8 秒	4.3 秒
新しいアクティビティ発生後のグローバル検索	約 14 秒	約 2 秒
ウォーム状態での list（4.5k セッション）／ウォーム検索	0.3 秒／0.25 秒	同じ
メッセージ配信（送信 → 起動された受信側）	中央値 0.8 ms	同じ

Rust コア（native/、PyO3 abi3 ホイール）はオプションです。これを使用しない場合、puenteo は依存関係なしの純粋な Python のまま動作します。実際のログを使ったテストで、両方のパーサーがバイト単位で同一の出力を生成することを確認します。純粋な Python を強制するには PUENTEO_NATIVE=0 を設定してください。

MCP サーバー

puenteo mcp は依存関係のない stdio MCP サーバーで、エージェントセッションごとに 1 つのプロセスが起動します。親プロセスのチェーンから担当するセッションを検出してバスに登録し、次のツールを公開します：

• 履歴： sessions、search、outline、pull、show
• ライブ： whoami、peers、send、reply、inbox、wait、thread、channels、subscribe、set_name、claim、release、claims

puenteo install は Claude Code（claude mcp add -s user）、Codex（codex mcp add）、Gemini、Qwen、Cursor、OpenCode、Copilot、Antigravity 向けに登録します。

履歴の検索と取得

puenteo search "gatekeeper dmg" --exclude-self       # ranked over ALL sessions (FTS5 index), ~0.2 s
puenteo search "topic" --cwd . --since 2026-09-01
puenteo list --cwd . -n 20                            # git-style unique id prefixes
puenteo outline <ref>                                 # milestones with message #index
puenteo pull <ref> --mode handoff                     # goal + decisions + latest state, budgeted
puenteo pull <ref> --query "topic" --mode query       # relevant messages + neighbours
puenteo pull <ref> --around 500 --radius 5
puenteo show <ref> --range 100:120
puenteo export <ref> -f md|html|pdf|json|zip|csv|xml|yaml|all -o out
puenteo index --stats                                 # the index refreshes itself; --clear to reset

<ref> には、一意な ID のプレフィックス、provider:id、@self、@last、@last:codex、パス、またはタイトルの一部を指定できます。曖昧なプレフィックスを指定すると、終了コード 4 で失敗し、候補が表示されます。puenteo が黙って選択することはありません。

ライブラリ

import puenteo

for s in puenteo.list_sessions(limit=10, cwd="~/dev/myapp"):
    print(s.provider, s.session_id, s.title)

hits = puenteo.search("gatekeeper dmg", exclude_session="my-current-id")
msgs = puenteo.pull(hits[0].session.session_id, query="dmg", mode="query")
puenteo.export_session("019f7a24", fmt="md", output="chat.md")

from puenteo.bus import Bus
with Bus() as bus:
    bus.send("claude:8765…", "@reviewer", "PR ready")
    for m in bus.inbox("codex:01a1…"):
        print(m.sender, m.body)

プロバイダー

プロバイダー	保存先
Claude Code	~/.claude/projects/**/*.jsonl（meta エントリーはスキップされ、ストリーミングされた断片は結合されます）
Codex	~/.codex/sessions/**/rollout-*.jsonl ＋ タイトル用の state_*.sqlite。サブエージェントはそれぞれ独自の ID を保持します
Gemini CLI	~/.gemini/tmp/**
Antigravity	~/.gemini/antigravity/brain/*/…/transcript*.jsonl
Grok	~/.grok/sessions/**/chat_history.jsonl
Pi	~/.pi/agent/sessions/**/*.jsonl
Qwen Code	~/.qwen/projects/**/chats/*
Cursor	macOS ~/Library/Application Support/Cursor · Linux ~/.config/Cursor · Windows %APPDATA%\Cursor
Continue	~/.continue/sessions/**
Aider	.aider.chat.history.md（--cwd または PUENTEO_AIDER_ROOTS でスキャン）
OpenHands	~/.openhands/openhands.db
Goose	~/.config/goose · Windows %APPDATA%\goose

ライブ検出（ps）は、Claude Code（~/.claude/sessions）、Codex（スレッドロック）、Grok、Junie、および puenteo MCP サーバーまたはフックを実行するすべてのエージェントに対応しています。

各種データの保存場所

項目	パス（macOS / Linux / Windows）	オーバーライド
検索インデックス ＋ メタデータキャッシュ	~/Library/Caches/puenteo · ~/.cache/puenteo · %LOCALAPPDATA%\puenteo\Cache	PUENTEO_HOME、PUENTEO_NO_INDEX=1、PUENTEO_NO_CACHE=1
メッセージバス	~/Library/Application Support/puenteo/bus.db · ~/.local/state/puenteo · %LOCALAPPDATA%\puenteo\State	PUENTEO_BUS
ID	自動検出	PUENTEO_SESSION=agent:id、--as

スキル（エージェントが学ぶこと）

puenteo install を実行すると、すべてのエージェントに目的別の 11 個のスキルが提供されます。エージェントは通常のリクエストから適切なスキルを選ぶため、コマンドを覚えておく必要はありません。

こう言うと…	スキル
「puenteo をセットアップして」「エージェントを接続して」	puenteo-setup
「X についてどこで話した？」「昨日 codex は何をした？」	puenteo
「別のウィンドウに聞いて」「codex に伝えて…」	puenteo-bus
「別のセッションが止まったところから続けて」	puenteo-handoff
「2 人でこのリポジトリを編集しています」	puenteo-team
「別のノート PC のエージェントに聞いて」	puenteo-mesh
「ダッシュボードを開いて」、REST/SSE/A2A	puenteo-dashboard
「そのチャットを PDF にして」	puenteo-export
「エージェントに答えるボット」、Python API	puenteo-automation
「エージェント X をサポートして」、プラグイン	puenteo-plugin-dev
「puenteo が動かない」	puenteo-troubleshoot

スキルに記載されたすべてのコマンドは、CI で実際の CLI に対して検証されます（tests/test_skills.py）。evals/run_skill_eval.sh は、実際の Claude Code セッションを使って適切なスキルが読み込まれることを確認します。

拡張する

新しいエージェントの保存先、MCP ツール、配信チャネル（Slack、IDE…）、またはライブ検出機能を追加しますか？ プラグインを作成してください。エントリーポイントを備えた通常のパッケージなので、フォークする必要はありません。docs/PLUGINS.md と examples/puenteo-example-plugin のテンプレートを参照してください。puenteo plugins を実行すると、読み込まれているプラグインを確認できます。

個人、企業、AI エージェントによるコアへの貢献は、いずれも同じ審査を経ます。3 つの OS での CI、依存関係ゼロのチェック、セキュリティスキャン、DCO への同意、およびコードオーナーによるレビューです。CONTRIBUTING.md と GOVERNANCE.md を参照してください。

開発

python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest -q                         # hermetic (fake $HOME)
PUENTEO_LIVE_TESTS=1 .venv/bin/python -m pytest -q    # plus checks against your real stores

ロードマップについては、docs/PLAN.md を参照してください。

ライセンス

MIT · mano7onam/puenteo