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.

[puenteo dashboard: four agents from different vendors coordinating a schema change]

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

[PyPI] [CI] [MCP Registry] [License: MIT]

Install

uv tool install puenteo        # or: pipx install puenteo / pip install puenteouv tool install 'puenteo[fast]'  # + optional Rust core: 3–8x faster parsing and indexingpuenteo install                # skills + MCP server into every detected agentpuenteo install --hooks        # optional: deliver messages through Claude Code / Codex hookspuenteo 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/puenteoclaude 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 300puenteo send @reviewer "PR ready: feat/x"          # peers can pick a name: puenteo join --name reviewerpuenteo send cwd:. "Refactoring src/db, keep out for 30 min"   # everyone in this projectpuenteo send '#release' "v0.7 tagged"             # channels (posting joins)puenteo send agent:codex "…"   |   puenteo send '*' "…"puenteo inbox                                     # read your messagespuenteo reply <msg-id> "answer"                   # routes back to the sender or channelpuenteo wait -t 120                               # block until a message arrivespuenteo watch                                     # stream incoming messages (for an agent's monitor)puenteo log -f                                    # watch all bus trafficpuenteo claim src/db --note "migration 0042"      # advisory lock; conflicts with overlapping claimspuenteo 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.

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 spuenteo search "topic" --cwd . --since 2026-09-01puenteo list --cwd . -n 20                            # git-style unique id prefixespuenteo outline <ref>                                 # milestones with message #indexpuenteo pull <ref> --mode handoff                     # goal + decisions + latest state, budgetedpuenteo pull <ref> --query "topic" --mode query       # relevant messages + neighbourspuenteo pull <ref> --around 500 --radius 5puenteo show <ref> --range 100:120puenteo export <ref> -f md|html|pdf|json|zip|csv|xml|yaml|all -o outpuenteo 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 Buswith 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

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