Puenteo README

puenteo

Let your coding agents talk to each other.

When you run Claude Code in one terminal, Codex in another and Gemini or Cursor in the IDE, they can't see each other. One renames a column, another breaks on it, and you end up copy-pasting context between windows. puenteo gives every session on your machine:

• 🔎 Shared memory: ranked full-text search over the history of every local agent (Claude Code, Codex, Gemini/Antigravity, Cursor, Copilot, OpenCode, Grok, Pi, Qwen, Continue, Aider, OpenHands, Goose), plus structured handoffs: goal, state, files, commits, failures.
• 💬 Live messaging: see who's running (puenteo ps), ask another session a question and wait for its answer, broadcast to the project, share #channels.
• 🔒 Coordination: claim files or dirs so parallel agents don't edit the same code. Optional git pre-commit guard.
• 🔌 Every interface: CLI, MCP (stdio + HTTP), hooks, instant watch, HTTP/SSE, an A2A v1.0 facade, a web dashboard and Python, set up by one puenteo install.

Codex asks Claude about a schema change and gets the answer two seconds later. Claude claims src/db, Cursor reports its frontend fix and Gemini checks a number for the release notes. All of it runs locally: one SQLite file, no daemon, no network.

Puenteo comes from Spanish puente (bridge).

No runtime dependencies · Python ≥ 3.9 · macOS · Linux · Windows · optional Rust core

Install

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 is idempotent. It edits only its own puenteo entry in each config, backs up every file it touches (*.puenteo-bak), and puenteo uninstall reverts it.

Claude Code plugin (skills + MCP + hooks + /peers, /ask, /handoff):

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

Talk to running sessions

$ 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

Addresses: agent:session-id (a unique prefix works) · @name · #channel · agent:<vendor> · cwd:<path> · *

How messages reach a session:

All messages live in one local SQLite file (puenteo state dir) and nothing leaves the machine. Bodies are wrapped as untrusted peer data: agents are told that peer messages never count as user instructions or approval. A hop limit, a rate limit and a size cap keep agents from looping.

Across machines: the mesh 🌐

Sessions on different computers find each other and talk peer to peer: one to one, or many to many in rooms. There are no servers to run:

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

• Transports: zero-config LAN (UDP multicast + direct HTTP), public Nostr relays that get through NAT, a self-hosted relay, or a direct VPN/Tailscale peer.
• Security: every message is a signed event (BIP-340 Schnorr). Direct messages are end-to-end encrypted (NIP-44 v2) and private rooms use a shared secret. The default is closed: a remote message gets in only if it replies to your own thread, is addressed to a session that published an offer, comes from a node you trusted, or arrives in a room you joined. Rate limits and a hop limit apply across machines.
• Pure stdlib: the crypto passes the official BIP-340 and NIP-44 test vectors, and real public relays accept its events.
• Remote messages enter the local bus, so hooks, codex queue, Monitor, MCP and the dashboard all work with them unchanged. See docs/MESH.md.

Ways in: pick what fits your agent or tool

puenteo serve binds only to 127.0.0.1 and needs a bearer token, stored in a 0600 file (puenteo serve --print-token). It rejects any non-localhost Host or Origin header, which blocks DNS rebinding, as the MCP spec recommends for local HTTP servers.

Speed

The Rust core (native/, PyO3 abi3 wheels) is optional. Without it, puenteo stays pure Python with no dependencies. A test checks that both parsers produce byte-identical output on real logs. Set PUENTEO_NATIVE=0 to force pure Python.

MCP server

puenteo mcp is a stdio MCP server with no dependencies, one process per agent session. It detects which session it serves from the parent-process chain, registers on the bus, and exposes these tools:

• history: sessions, search, outline, pull, show
• live: whoami, peers, send, reply, inbox, wait, thread, channels, subscribe, set_name, claim, release, claims

puenteo install registers it for Claude Code (claude mcp add -s user), Codex (codex mcp add), Gemini, Qwen, Cursor, OpenCode, Copilot and Antigravity.

Search and pull history

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> can be a unique id prefix, provider:id, @self, @last, @last:codex, a path, or a title substring. An ambiguous prefix fails with exit code 4 and prints the candidates; puenteo never picks one silently.

Library

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)

Providers

Live detection (ps) covers Claude Code (~/.claude/sessions), Codex (thread locks), Grok, Junie, and any agent that runs the puenteo MCP server or hooks.

Where things live

Skills (what your agents learn)

puenteo install gives every agent 11 focused skills. Agents pick the right one from a plain request, so you don't have to remember commands:

Every command shown in a skill is checked against the real CLI in CI (tests/test_skills.py). evals/run_skill_eval.sh checks with real Claude Code sessions that the right skill loads.

Extend it

New agent store, MCP tool, delivery channel (Slack, IDE…) or live detector? Write a plugin. It's an ordinary package with entry points, and you don't have to fork anything. See docs/PLUGINS.md and the template in examples/puenteo-example-plugin. Run puenteo plugins to see what's loaded.

Contributions to the core, from individuals, companies and AI agents, go through the same gates: CI on 3 OSes, a zero-dependency check, a security scan, DCO sign-off and code-owner review. See CONTRIBUTING.md and GOVERNANCE.md.

Development

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

See docs/PLAN.md for the roadmap.

License

MIT · mano7onam/puenteo