Puenteo

puenteo

让你的编码 Agent 彼此交流。

当你在一个终端中运行 Claude Code，在另一个终端中运行 Codex，并在 IDE 中运行 Gemini 或 Cursor 时，它们彼此看不到对方。一个重命名了列，另一个因此出错，最后你只能在窗口之间复制粘贴上下文。puenteo 为你机器上的每个会话提供：

• 🔎 共享记忆：对每个本地 Agent 的历史记录进行排序全文搜索（Claude Code、Codex、Gemini/Antigravity、Cursor、Copilot、OpenCode、Grok、Pi、Qwen、Continue、Aider、OpenHands、Goose），并支持结构化交接：目标、状态、文件、提交、失败。
• 💬 实时消息：查看谁正在运行（puenteo ps），向另一个会话提问并等待回复，向项目广播，共享 #channels。
• 🔒 协作协调：认领文件或目录，避免并行 Agent 编辑相同代码。可选的 git 提交前防护。
• 🔌 支持所有接口：CLI、MCP（stdio + HTTP）、hooks、即时 watch、HTTP/SSE、A2A v1.0 门面、Web 仪表板和 Python，只需运行一次 puenteo install 即可完成设置。

Codex 向 Claude 询问架构变更，并在两秒后收到答复。Claude 认领了 src/db，Cursor 报告了其前端修复，Gemini 则为发行说明核对一个数字。所有操作都在本地运行：一个 SQLite 文件，无守护进程，无网络。

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 + hooks + /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> · *

消息如何到达会话：

Agent	空闲时唤醒	工作期间
Codex	是，通过 codex queue 推送	hooks / MCP inbox
Claude Code	是，当会话在其 Monitor 工具下运行 puenteo watch 时	hooks（install --hooks）/ MCP inbox
Gemini、Cursor、OpenCode、Copilot、Qwen 等	否；消息会留在收件箱中	MCP inbox / wait

所有消息都存储在一个本地 SQLite 文件（puenteo 状态目录）中，不会离开这台机器。消息正文会被包装为不可信的同伴数据：Agent 会收到指示，明确同伴消息绝不能视为用户指令或批准。跳数限制、速率限制和大小上限可避免 Agent 陷入循环。

跨机器：网状网络 🌐

不同计算机上的会话会彼此发现并进行点对点通信：可以一对一，也可以在房间中多对多。无需运行任何服务器：

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

• 传输方式：零配置局域网（UDP 多播 + 直接 HTTP）、可穿透 NAT 的公共 Nostr 中继、可自托管的中继，或直接连接 VPN/Tailscale 节点。
• 安全性：每条消息都是经过签名的事件（BIP-340 Schnorr）。私信采用端到端加密（NIP-44 v2），私密房间则使用共享密钥。默认情况下采取封闭策略：只有在远程消息回复了你自己的线程、发给了发布过邀请的会话、来自你信任的节点，或送达你加入的房间时，消息才会进入。机器之间也会应用速率限制和跳数限制。
• 纯标准库：加密实现通过了官方 BIP-340 和 NIP-44 测试向量验证，公共中继也能接受其事件。
• 远程消息会进入本地总线，因此钩子、codex queue、Monitor、MCP 和仪表板都能照常处理这些消息。详见 docs/MESH.md。

接入方式：选择适合你的 Agent 或工具

接口	用途	命令 / 端点
CLI	任何可使用 shell 的 Agent、脚本	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 / stream	邮件到达时立即唤醒处于空闲状态的 Claude 会话	puenteo watch（即时；通过 Unix 套接字门铃）
Exec trigger	为任何工具提供衔接：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	标准的 Agent 对 Agent 客户端	/.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 文件中的 Bearer 令牌（puenteo serve --print-token）。它会拒绝任何非本地主机的 Host 或 Origin 标头，从而阻止 DNS 重绑定；这也是 MCP 规范对本地 HTTP 服务的建议。

速度

	纯 Python	使用 puenteo[fast]（Rust 核心）
解析对话记录（最大的 25 个，共 3.3 GB）	~300 MB/s	0.8–2.7 GB/s，使用所有核心
冷启动重建索引（807 个 Codex + Claude 会话，约 4 GB）	14.8 s	4.3 s
新活动后的全局搜索	~14 s	~2 s
热启动 list（4.5k 个会话）/ 热启动搜索	0.3 s / 0.25 s	相同
消息传递（发送 → 唤醒接收方）	中位数 0.8 ms	相同

Rust 核心（native/，PyO3 abi3 轮子）为可选组件。没有它时，puenteo 仍是纯 Python，无需依赖项。测试会检查两个解析器在真实日志上是否生成逐字节完全相同的输出。设置 PUENTEO_NATIVE=0 可强制使用纯 Python。

MCP 服务

puenteo mcp 是一个无依赖的 stdio MCP 服务，每个 Agent 会话启动一个进程。它会根据父进程链检测自己服务的会话，在总线上注册，并提供以下工具：

• 历史记录： 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 标题；子 Agent 保留各自的 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 服务或钩子的 Agent。

文件位置

内容	路径（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
身份	自动检测	PUENTEO_SESSION=agent:id、--as

技能（Agent 可学会的内容）

puenteo install 会为每个 Agent 安装 11 个专用技能。Agent 会根据普通请求选择合适的技能，因此你无需记住命令：

你可以这样说……	技能
“设置 puenteo”、“连接我的 Agent”	puenteo-setup
“我们在哪里讨论过 X”、“codex 昨天做了什么”	puenteo
“问问另一个窗口”、“告诉 codex …”	puenteo-bus
“从另一个会话停止的地方继续”	puenteo-handoff
“我们都在编辑这个仓库”	puenteo-team
“问问我另一台笔记本电脑上的 Agent”	puenteo-mesh
“打开仪表板”、REST/SSE/A2A	puenteo-dashboard
“把那段聊天导出为 PDF”	puenteo-export
“一个能回答 Agent 问题的机器人”、Python API	puenteo-automation
“支持 Agent X”、插件	puenteo-plugin-dev
“puenteo 无法正常工作”	puenteo-troubleshoot

技能中展示的每条命令都会在 CI 中与实际 CLI 核对（tests/test_skills.py）。evals/run_skill_eval.sh 会使用真实的 Claude Code 会话检查是否加载了正确的技能。

扩展

想新增 Agent 存储、MCP 工具、交付渠道（Slack、IDE……）或实时检测器？编写一个插件即可。它就是带有入口点的普通软件包，无需分叉任何内容。请参阅 docs/PLUGINS.md 和 examples/puenteo-example-plugin 中的模板。运行 puenteo plugins 可查看已加载的插件。

个人、公司和 AI Agent 对核心项目的贡献都要经过相同的审核流程：在 3 种操作系统上运行 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