Puenteo

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 "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: · cwd: · *

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 "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 # milestones with message #index puenteo pull --mode handoff # goal + decisions + latest state, budgeted puenteo pull --query "topic" --mode query # relevant messages + neighbours puenteo pull --around 500 --radius 5 puenteo show --range 100:120 puenteo export -f md|html|pdf|json|zip|csv|xml|yaml|all -o out puenteo index --stats # the index refreshes itself; --clear to reset

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

| Qwen Code | `~/.qwen/projects/**/c