Enables coding agents to share memory, message each other live, and coordinate file access across different local or remote sessions.
Also known as mano7onam/puenteo
- Stars
- 1
- Tools
- β
- Downloads, 30 days
- 143
- Latest version
- 0.13.0
- Last commit
- Oct 14, 2026
- License
- MIT
What is Puenteo MCP?
Puenteo enables coding agents to share memory, message each other live, and coordinate file access across different local or remote sessions.
Summary generated from the project's README
About Puenteo MCP server
Puenteo provides a coordination layer for coding agents to communicate and share context across different environments. It allows developers to connect various tools like Claude Code, Codex, Cursor, and Gemini, enabling them to share memory and message each other in real time. The system works locally using a single SQLite file, ensuring that all data stays on your machine without requiring a central server or network connection.
Users can manage sessions through a CLI, a web dashboard, or an MCP server. The platform supports structured handoffs of goals and states, ranked full-text search over agent histories, and file coordination to prevent multiple agents from editing the same directory simultaneously. For teams working across different computers, it offers a mesh capability using zero-config LAN or Nostr relays to facilitate peer-to-peer communication between remote sessions.
What you can do with it
- 1Synchronize agent contextAsk one coding agent about a specific schema change performed by another session.
- 2Prevent file edit conflictsClaim a specific directory so that parallel agents do not attempt to modify the same code.
- 3Search across all sessionsPerform a ranked full-text search to find specific topics or history within all local agent logs.
- 4Coordinate remote developersSend messages to agents running on different machines through a peer-to-peer mesh.
Written from the project's README. Every use case is checked against a quote from it.
How to install Puenteo MCP
Formats verified 10 Nov 2026Install Puenteo MCP in Claude Code
$ claude mcp add puenteo -- uvx puenteoInstall Puenteo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"puenteo": {
"command": "uvx",
"args": [
"puenteo"
]
}
}
}Install Puenteo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"puenteo": {
"type": "stdio",
"command": "uvx",
"args": [
"puenteo"
]
}
}
}Install Puenteo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"puenteo": {
"command": "uvx",
"args": [
"puenteo"
]
}
}
}Install Puenteo MCP in Codex
~/.codex/config.toml
[mcp_servers.puenteo] command = "uvx" args = ["puenteo"]
Install Puenteo MCP in Gemini CLI
~/.gemini/settings.json
{
"mcpServers": {
"puenteo": {
"command": "uvx",
"args": [
"puenteo"
]
}
}
}Configuration
PUENTEO_LIVE_TESTS
| Name | Description | |
|---|---|---|
| PUENTEO_LIVE_TESTS | β |
Automated checks
Ran Nov 13, 2026Full report βPassed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemano7onam/puenteo is public and reachablegithub.com/mano7onam/puenteo βPass
- Package names this repository as its sourcepuenteo names mano7onam/puenteo as sourcepypi.org/project/puenteo/ βPass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html βPass
- Commit or release in the last yearLast commit or release 2026-10-14github.com/mano7onam/puenteo βPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from puenteoPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev βPass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubpuenteo
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 onepuenteo 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:
| Agent | Woken while idle | While working |
|---|---|---|
| Codex | yes, pushed via codex queue |
hooks / MCP inbox |
| Claude Code | yes, when the session runs puenteo watch under its Monitor tool |
hooks (install --hooks) / MCP inbox |
| Gemini, Cursor, OpenCode, Copilot, Qwen, β¦ | no; the message waits in the inbox | MCP inbox / wait |
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
| Interface | Use it for | Command / endpoint |
|---|---|---|
| CLI | any agent with a shell, scripts | puenteo send/inbox/ps/search β¦ (--json everywhere) |
| MCP (stdio) | Claude Code, Codex, Gemini, Cursor, OpenCode, Copilot, Qwen | puenteo mcp (installed by puenteo install) |
| Hooks | messages show up in context with no tool call | puenteo install --hooks (Claude Code, Codex) |
| Monitor / stream | wake an idle Claude session the moment mail arrives | puenteo watch (instant; Unix-socket doorbell) |
| Exec trigger | glue for anything: notify-send, Slack, scripts | puenteo watch --exec 'cmd' (message JSON on stdin) |
| HTTP REST + SSE | dashboards, editors, other languages | puenteo serve β /api/*, /api/events |
| MCP over HTTP | MCP clients that prefer HTTP | POST /mcp on puenteo serve |
| A2A v1.0 | standard agent-to-agent clients | /.well-known/agent-card.json, POST /a2a |
| Web dashboard | watching and talking to all sessions in a browser | puenteo serve --open |
| Python | your own orchestrators | puenteo.send(), for m in puenteo.listen(): β¦, puenteo.Bus |
| Git guard | stop commits that touch a file a peer claimed | puenteo guard install |
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
| pure Python | with puenteo[fast] (Rust core) |
|
|---|---|---|
| parse transcripts (25 largest, 3.3 GB) | ~300 MB/s | 0.8β2.7 GB/s, all cores |
| cold index rebuild (807 Codex + Claude sessions, ~4 GB) | 14.8 s | 4.3 s |
| global search after new activity | ~14 s | ~2 s |
warm list (4.5k sessions) / warm search |
0.3 s / 0.25 s | same |
| message delivery (send β woken reader) | 0.8 ms median | same |
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
| Provider | Store |
|---|---|
| Claude Code | ~/.claude/projects/**/*.jsonl (meta entries skipped, streamed fragments merged) |
| Codex | ~/.codex/sessions/**/rollout-*.jsonl + state_*.sqlite titles; subagents keep their own ids |
| 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 (scan with --cwd or PUENTEO_AIDER_ROOTS) |
| OpenHands | ~/.openhands/openhands.db |
| Goose | ~/.config/goose Β· Windows %APPDATA%\goose |
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
| What | Path (macOS / Linux / Windows) | Override |
|---|---|---|
| Search index + metadata cache | ~/Library/Caches/puenteo Β· ~/.cache/puenteo Β· %LOCALAPPDATA%\puenteo\Cache |
PUENTEO_HOME, PUENTEO_NO_INDEX=1, PUENTEO_NO_CACHE=1 |
| Message bus | ~/Library/Application Support/puenteo/bus.db Β· ~/.local/state/puenteo Β· %LOCALAPPDATA%\puenteo\State |
PUENTEO_BUS |
| Identity | detected automatically | PUENTEO_SESSION=agent:id, --as |
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:
| You say⦠| Skill |
|---|---|
| "set up puenteo", "connect my agents" | puenteo-setup |
| "where did we discuss X", "what did codex do yesterday" | puenteo |
| "ask the other window", "tell codex β¦" | puenteo-bus |
| "continue where the other session stopped" | puenteo-handoff |
| "we're both editing this repo" | puenteo-team |
| "ask the agent on my other laptop" | puenteo-mesh |
| "open the dashboard", REST/SSE/A2A | puenteo-dashboard |
| "make a PDF of that chat" | puenteo-export |
| "a bot that answers agents", Python API | puenteo-automation |
| "support agent X", plugins | puenteo-plugin-dev |
| "puenteo doesn't work" | puenteo-troubleshoot |
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
Puenteo MCP questions
How do I add Puenteo MCP to Claude Code?
Run claude mcp add puenteo -- uvx puenteo in your terminal. Add --scope user to make it available in every project.
How do I add Puenteo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does my data leave my machine?
No, all messages and data live in a local SQLite file and nothing leaves the machine unless you explicitly set up a mesh or relay.
Can agents on different computers communicate?
Yes, through a mesh service that uses zero-config LAN, Nostr relays, or a self-hosted relay to allow peer-to-peer communication.
How do I install it for my agents?
You can use the 'puenteo install' command to add skills and the MCP server to all detected agents.