plumb

README

IDE intelligence for agents — with guardrails for unattended work.

Plumb is an MCP server that gives a coding agent the intelligence layer of an IDE — LSP-backed semantics, a tree-sitter code index, and project memory — inside guardrails: atomic, lock-serialised writes with transactional rollback, scoped filesystem and git access, and a daemon that survives its own crashes. A single binary; nothing else to install.

---

Why Plumb

LLM agents usually work by reading whole files into the context window — token-heavy, lossy at scale, blind to symbol semantics, and unsafe to let loose on a real repo. Plumb is built on three pillars, in priority order.

1. Reliability & write-safety

Leaving an agent to edit a codebase for an hour is only viable if writes can't corrupt files and a crash can't wedge your session.

• Atomic I/O — every write is staged in a temp file and renamed into place. No partial writes, ever. Symlink-aware, CRLF-tolerant.
• Per-path locking — the daemon serialises concurrent writes to the same file across every session and chat window. No races.
• Multi-file transactions — apply edits across dozens of files with guaranteed atomic rollback if any step fails.
• Crash-resilient daemon — plumb serve is a reconnecting proxy. If the daemon crashes or hangs, it respawns one and replays the handshake; the agent never notices. In-flight writes are never silently re-run.
• Optimistic concurrency — mtime/sha guards catch stale edits before they clobber newer changes.

See it run: docs/demos/ has a self-contained two-agents-one-file demo where a stale write is refused with a clear message and nothing is lost.

2. Semantic intelligence

The same primitives your editor has, exposed as structured tools:

• LSP-backed refactors — rename_symbol, replace_symbol_body, safe_delete_symbol understand scope, types, and references.
• Real diagnostics inline — actual gopls/pyright output is appended to every write, so the agent learns it broke the build immediately.
• Symbol search — scoped to your code, no stdlib or dependency noise.

3. Context efficiency & safety controls

• Read only what you need — symbols or line ranges, not 2,000-line files.
• Scoped access you control — a per-connection path allowlist (read-only vs read-write roots) plus tiered git gating (destructive and network operations are off by default and need explicit confirmation). See SECURITY.md.
• One-round-trip bootstrap — session_start returns workspace, branch, recent commits, diagnostics, and project memory.

See the measured, reproducible numbers behind this: docs/use-cases.md — reading one function is ~8× less context than the whole file, and find_references returns the real call sites where a text search is ~44% noise.

---

Get started

Plumb is a single binary — from zero to your first answer:

1. Install

# Homebrew (macOS + Linux) — recommended
brew install plumbkit/plumb/plumb

# or with Go
go install github.com/plumbkit/plumb/cmd/plumb@latest

# or grab a prebuilt binary: https://github.com/plumbkit/plumb/releases

macOS note: prebuilt binaries are not yet notarised — on first run you may need xattr -d com.apple.quarantine ./plumb, or right-click → Open. Homebrew installs avoid this.

2. Connect your agent

plumb setup claude-code      # also: claude-desktop, codex, gemini, cursor, …

plumb setup writes the MCP config for you — no hand-editing JSON.

3. Open your project and try it

Make sure the language server you need is on your $PATH (gopls for Go, pyright for Python, …), then point your agent at a real question. In Claude Code:

cd your/project
claude "Use plumb to orient in this repo (session_start), then show me
everywhere <Handler> is called and what would break if I changed its signature."

Plumb resolves the workspace and runs session_start for orientation, then answers with real LSP and topology data — actual call sites and blast radius — instead of guessing from file dumps. It's read-only; nothing is modified. (Any connected agent works — just paste the prompt.)

No go.mod/pyproject.toml and not a git repo? Run plumb init once to pin the workspace root (it also seeds .plumb/context.md and project config).

Full walkthrough → docs/getting-started.md.

---

Language support (honest version)

Plumb negotiates LSP capabilities per language and also ships a built-in tree-sitter index for search and navigation with no language server. Support comes in tiers — we'd rather be precise than claim a big number.

Tier	Languages	What you get
First-class (CI-tested, real-binary integration)	Go (gopls), Python (pyright)	Full LSP: definitions, references, rename, diagnostics, hierarchies + all write tools
Validated	Java (jdtls), Rust (rust-analyzer), Swift (sourcekit-lsp)	Full LSP; just put the server on $PATH and it activates automatically
Experimental	TypeScript/JS, Kotlin, Zig, HTML	Navigation works against the real servers; diagnostics validation is still in progress. Put the server on $PATH to activate (exclude any language with [lsp.<lang>] enabled = false)
Search & navigation (tree-sitter, no LSP needed)	15+ incl. JS/TS/TSX, Bash, SQL, HCL, Dockerfile, TOML, YAML, Markdown	Ranked symbol search, outlines, graph exploration via the Topology index

Real-binary validation has been exercised on macOS; Linux integration runs in CI and is being hardened pre-v1. Windows is tracked but not yet supported — the daemon's Unix-socket architecture needs a port.

---

How it works

plumb serve is a thin, reconnecting stdio proxy. The real work happens in one shared background daemon, so language servers stay warm across chats.

flowchart TD
    A1["Claude"] --> S1["plumb serve *"]
    A2["Codex"] --> S2["plumb serve *"]
    A3["Gemini"] --> S3["plumb serve *"]
    S1 --> K["plumb.sock"]
    S2 --> K
    S3 --> K
    K --> D["plumb daemon **"]
    D --> G["gopls → /projects/foo"]
    D --> P["pyright → /projects/bar"]

* plumb serve is a reconnecting proxy — if the daemon crashes or hangs it respawns one and replays the handshake, so your session survives without the agent noticing.

** one shared process, reused across every conversation.

Servers stay warm across chats, per-path locks are shared across every connection, and symbol indexes update live after each write. Full architecture → docs/architecture.md.

---

Monitoring (TUI)

Run plumb with no arguments for a live dashboard — see what your agent is doing in real time: every tool call as it happens, daemon health, per-tool stats, and streaming logs you can follow and filter. The fastest way to catch a runaway loop or confirm an edit landed.

---

Core capabilities

Plumb exposes 53 tools. The ones you'll use constantly:

session_start · find_symbol · get_definition · find_references · rename_symbol · edit_file · transaction_apply · diagnostics

The rest cover filesystem reads/writes, LSP hierarchies, tiered git, an optional local Topology index (ranked search + blast-radius/route analysis, no language server needed), and durable per-project memory. Full API reference: docs/tools.md.

---

Configuration

Global or per-project config.toml, or environment variables. Run plumb config show to see the resolved config with provenance.

[edits]
strict = true                  # require read_file before edit_file
rate_limit_per_minute = 30     # bound runaway agent loops

[git]
allow_destructive = false      # reset/checkout/rebase off by default
allow_push = false             # push/fetch/pull off by default

Full settings reference: docs/configuration.md.

---

The hard part

Agents can already read code well enough; writing it unsupervised — concurrently, transactionally, recoverably — is what's still unsolved. Plumb is the bet that this is the half worth getting right first. It's early, and the language coverage says so: a small validated core, the rest clearly marked experimental.

---

Roadmap

Plumb is pre-1.0. The core — write-safety, the resilient daemon, the topology index, and project memory — is in daily use. The road to 1.0 is mostly about proving it beyond the validated core and smoothing distribution. Issues and ideas welcome.

Shipped

• Concurrency-safe, atomic, transactional writes with rollback
• Crash-resilient reconnecting daemon
• Tree-sitter topology index + per-project memory
• Go and Python LSP adapters validated (real-binary)

Road to 1.0

• Green Linux CI with real-binary LSP integration (today: validated on macOS; Linux hardening in progress)
• Homebrew distribution (brew install plumb)
• Promote experimental adapters to validated — pull-diagnostics support so Zig / TypeScript / Kotlin pass end-to-end
• Swift on Xcode projects: build-server (BSP) guidance so semantic tools work without a SwiftPM manifest
• Semantic re-rank for topology search → GA (today: opt-in, off by default)

Exploratory / post-1.0

• Native Windows support
• Retire the WASM tree-sitter path once the pure-Go parser handles Swift IUO and TS typed-arrow

Contributing

See CONTRIBUTING.md and AGENTS.md for architecture and code style. We follow Australian English in all prose. By contributing you agree to the Code of Conduct.

License

MIT — see LICENSE.