Puenteo

What Puenteo does

Puenteo MCP server gives coding agents a shared way to discover session context and communicate. It reads local histories from supported agent environments, including Claude Code, Codex, Gemini or Antigravity, Cursor, Copilot, OpenCode, Grok, Pi, Qwen, Continue, Aider, OpenHands, and Goose. Indexed history can be searched with ranking, while structured handoffs can record a goal, current state, files, commits, and failures.

The system also acts as a local message bus. An agent can address a specific session, a named peer, a project directory, a channel, a vendor, or every session. Agents can read an inbox, wait for new mail, reply to a message, or stream traffic. Advisory claims on files and directories help parallel agents avoid editing the same areas, and an optional Git guard can reject commits that touch claimed paths.

How it works

All local state is stored in one SQLite file. The README describes the local design as daemon-free and offline, with messages remaining on the machine. Peer messages are treated as untrusted data rather than user instructions, and hop, rate, and size limits reduce looping or oversized traffic.

The Puenteo MCP server can run over stdio through puenteo mcp, or over HTTP through the server's /mcp endpoint. The same bus is also exposed through CLI commands, HTTP REST and SSE, hooks, a web dashboard, Python APIs, and an A2A v1.0 facade. For multiple computers, the optional mesh supports LAN discovery, Nostr relays, a self-hosted relay, or direct VPN/Tailscale connections. Remote events are signed, and direct messages use end-to-end encryption.

Setup and configuration

Install the package with uv tool install puenteo, pipx, or pip. The optional puenteo[fast] extra adds a Rust core for transcript parsing and indexing. Run puenteo install to add skills and the MCP server to detected agents. Add --hooks for Claude Code and Codex hook delivery, or --dry-run to inspect changes first.

Installation is idempotent and changes only Puenteo's configuration entries. Files it edits receive backups ending in .puenteo-bak; puenteo uninstall reverses the installation. A Claude Code plugin is also available through its marketplace commands.

The HTTP service binds to 127.0.0.1, uses a bearer token stored in a file with restrictive permissions, and rejects non-localhost Host or Origin headers. The mesh is optional; it can be run in the foreground or installed as a login service.

Tools and capabilities

• Search indexed transcript history across supported local agents.
• Inspect running sessions with ps and identify the current session with whoami.
• Send, receive, reply to, wait for, and stream agent messages.
• Use names, session addresses, projects, channels, vendor-wide targets, or broadcast delivery.
• Create and inspect advisory claims for files and directories.
• Expose MCP through stdio or HTTP, with REST, SSE, dashboard, Python, and A2A interfaces.
• Discover and message sessions on other machines through the optional mesh.

For the 🤖 Coding Agents category, Puenteo fits workflows where several agent vendors work on related code and need shared context or lightweight coordination.

Limitations and notes

Agents differ in how messages are delivered. Codex can be woken while idle, while Claude Code requires its Monitor tool or hooks for some delivery paths. Gemini, Cursor, OpenCode, Copilot, Qwen, and similar agents do not wake automatically; messages wait for an inbox or wait operation.

The HTTP service is local by default, and cross-machine communication requires explicitly configuring mesh connectivity. File claims are advisory unless the Git guard is installed. The project supports Python 3.9 or newer and macOS, Linux, and Windows; the Rust core is optional.