showme

showme gives a coding agent and the human reviewing its work one shared view of the code. The agent opens the locations it is talking about and annotates them at the line; the human marks a range in the editor and asks about it.

uv tool install git+https://github.com/schuay/showme-mcp
showme install claude # or codex, gemini, opencode -- shows the change and asks

Then ask your agent to show you something. It takes a session of its own, rooted at the directory it was started in; nvim starts with the first thing it shows, and a window opens for it if SHOWME_TERMINAL names your terminal. There is nothing to start and no key to paste.

One session per conversation, not per directory: two agents working in one tree get one each, so neither annotates over the other. A conversation you resume picks its session up again where the harness publishes an id for it (Claude Code does), and otherwise starts clean. Sessions nobody is using are collected.

showme new <root> still makes a session by hand and showme ls lists them. showme 3 attaches a terminal to one, and showme ~/src/thing attaches to the one last used in a tree. A sandboxed agent cannot reach that side at all, so its launcher passes it a key instead; see below.

The agent reaches the same session through MCP and puts code in front of you instead of quoting line numbers at you.

Using it

The agent has two tools. show opens a set of locations: a tab per file, a quickfix list of the positions, a highlight over any range, and a note above each line. read reports what you are looking at: your cursor and selection, the contents of an open buffer including unsaved edits, the open buffers, and the questions you have asked.

Notes live in frames. A show replaces the top frame by default; the agent can push a frame for a digression and pop it when answered, and every live frame stays on screen with the quickfix list walking the top one. Each note carries an id, A2 or B1, that you and the agent can both say.

On your side:

• Ctrl-Alt-PageDown and Ctrl-Alt-PageUp walk the quickfix list of notes, wrapping at the ends; Ctrl-Shift is left alone because terminals take it for their own scrollback.

• :3,5Ask why is this here? hands lines 3 to 5 and your question to the agent, tagged with the note it sits on. The agent collects questions with read, and a question stays pending until the agent has answered it.

• :Ref copies a reference to the current line, :7,9Ref to a range, in the form the agent reads them back: src/main.c:7-9, relative to the session root. It goes to the clipboard register, so nvim picks the tool your session uses.

• :AgentPop drops the top frame of notes; :AgentDrop B drops a named one.

• A question keeps its ?> sign until an agent acknowledges it, so a batch of replies shows which ones have come back.

• :q is safe. The broker holds the record of what is shown and starts nvim again, with the notes on the lines your edits moved them to.

Set SHOWME_TERMINAL in the shell you start sessions from, to a terminal and whatever it needs before a command -- ghostty -e, kitty, alacritty -e -- and a session gets a window of its own the first time an agent shows something to it while nothing is on screen. One window per nvim, so closing it closes it. An agent cannot ask for a window: it only ever happens because it showed you something you were not looking at.

Over ssh nothing can open, so the agent hands you the command instead. A show to a session with no terminal on it comes back saying nobody is watching and naming showme 3, which you run in a second shell on the same host; from then on the session is on your screen and shows land there. Run it before you ask for anything and there is nothing to hand over: the session exists from the moment the agent's client starts, so showme ls already lists it, and showme <root> reaches it without looking the id up.

Related MCP server: showme

How it fits together

A host-side broker daemon owns every session. nvim runs headless, so a session outlives the terminal you attach to and the agent that writes to it, and the broker keeps the record of notes and questions, so it outlives nvim too:

broker (host)  --msgpack-RPC-->  nvim --headless --listen
   ^                                  ^
   | MCP over a UNIX socket           | nvim --remote-ui
   |                                  |
MCP client, in a sandbox or not       your terminal, any terminal

Clients speak MCP itself over a UNIX socket. The client side is a small relay between stdin/stdout and that socket that knows the framing and nothing of the tools, so the broker's tool list is its entire exposed surface. The relay survives a broker restart: it reconnects on the next call and replays the handshake, so the client never notices. The broker in turn survives its own restart by adopting the nvim it left running, with your unsaved edits in it.

A broker holds session.lua and its own code from the moment it started, so after changing either, showme restart-broker puts a new one on the same sockets and hands it the sessions. Changed Lua reaches a session when its nvim next starts, which :q does.

What the broker will not do

• No command writes a file, saves a buffer, or edits buffer text. The agent edits on disk with its own tools, and the broker reloads unmodified buffers.

• A sandboxed agent reads only inside the session's root. An agent on the host is not held to it: it reads your files with its own tools and edits them there, so a clamp would only refuse it the worktree next door. The root still says where its relative paths are taken from and where nvim runs. A human mark is outside both, because only the human creates one.

• No agent-supplied string reaches an Ex command line. A file named a`touch /tmp/x`.c runs the shell through :edit and through nvim_cmd's structured arguments alike, so paths are opened with bufadd.

• The session key is the capability. showme new sets the root on the host and prints an unguessable key; handing that key to an agent is what lets it use the session. Every key you can see is clamped to the root. The one that is not belongs to a client that asked for it over the admin socket, which no sandbox can reach -- reaching it is the proof that the client is you.

From a sandbox

The MCP client can run confined. The box needs one mount, the directory holding the agent socket, read-only:

~/.local/share/showme

connect works through a read-only mount and bind does not, so the box reaches the broker on the host, and the broker a client starts when nothing answers dies in there instead of serving a second, empty set of sessions under the key you pasted. Nothing else has to go in, and the nvim listen sockets must not: raw nvim RPC runs arbitrary Lua, so one of those sockets hands over the host. showme mcp is the command on both sides. The directory also holds a standalone copy of the relay, for a box without showme installed:

python3 ~/.local/share/showme/splice.py ~/.local/share/showme/agent.sock

Install

uv tool install git+https://github.com/schuay/showme-mcp
claude mcp add --scope user showme -- showme mcp  # or your client's equivalent

From a clone, uv tool install . installs that working tree instead.

For development:

uv sync
./scripts/install-hooks
.venv/bin/python -m pytest -q      # most tests drive a real nvim

State lives under ~/.local/state/showme: the session record, and logs for the broker and each session's nvim.