MCP server

Terminal Delight is an MCP server. An agent running in one of its panes can ask about the rest of the window: which panes exist and what each is running, what they printed, what tool another agent is calling right now.

It starts locked down. Nothing is readable until you turn the server on, in the MCP control panel (Ctrl+Shift+A in a pane). Even then only agent panes are visible unless you choose all panes. Writing is a second switch, and a write only ever restyles a pane, leaves a note, declares a deliverable, opens a document or puts work on a workbench. No tool can type into a terminal.

To connect an agent, register the relay as a stdio MCP server:

claude mcp add --scope user terminal-delight -- terminal-delight mcp

The relay finds the window it is running in by itself. Every answer ends with the window it came from, because several Terminal Delight windows can run on one machine.

Technical lists all twelve tools with their arguments, the switches, and the errors.

The server

The server speaks newline-delimited JSON-RPC 2.0, advertises MCP protocol 2025-06-18, names itself terminal-delight, and offers tools and logging. It answers for the panes of one window.¹

Connecting#

There are three ways in:

the relay

terminal-delight mcp, registered as a stdio server. It forwards each request to a running window over that window's control socket. It finds its own window by walking up its parent processes to the pane it was started in, so it needs no environment variable; --pid <N> picks a window explicitly. If the window is replaced mid-session, the relay reconnects to the same session once and says so on stderr. Each call waits up to ten seconds.

in-process

An MCP client that launches terminal-delight itself with TD_MCP set gets the server on the window's own stdio. This is the only way that receives pushed notifications.

one call from a script

terminal-delight ctl mcp rpc '<json>' hands one JSON-RPC line to a window.

The registration this machine uses, in ~/.claude.json:

"terminal-delight": { "type": "stdio", "command": "terminal-delight", "args": ["mcp"] }

A relay that located itself names its session and pane with every call. If that session isn't the window's, the call is refused with -32001, wrong window: this is terminal-delight session "1" (window 31337), and you asked for session "2". Nothing was read or written., so a relay pointed at the wrong window gets an error instead of someone else's panes.

The switches#

They live in the MCP control panel: Ctrl+Shift+A in a pane, or AGENTS · MCP in the footer's … menu. From a script: ctl mcp on|off, ctl mcp writes on|off, ctl mcp expose agents|all. Each change is saved with the session. TD_MCP starts the in-process transport but does not turn the server on, and TD_MCP_WRITE turns writes on only alongside TD_MCP.

Tools#

Where a tool takes a pid, leaving it out means your own pane, which only works through the relay because only the relay says who is calling. Without it you get no `pid`, and this connection did not say who is calling — pass a pid from list_panes. A write to a pane the policy hides is refused.

Appearance#

get_pane_config and set_pane_config use 0 to 100 percent for brightness, contrast, colour, text, background, gamma, menu_bar, text_size, bench_size, warp, crawl_angle and crawl_depth, plus crawl as true or false, and logo as an image path for a pane. An update names only what changes; a misspelled channel is an error. The values are absolute, so "20 % lower" is yours to compute from a read. On a pane, only the channels you set become its own; outer changes every pane that follows the window.

Every answer says where it came from#

Each tool result, errors included, ends with a line like — terminal-delight · session 1 · window 31337 · td-81ec545-rows-where-drawn and carries the same in structuredContent.instance. To find your own pane in list_panes, match its pane <n> against $TD_PANE_ID; titles and directories are not unique.

Pushed notifications#

Over the in-process transport, after initialize and with events on, the server pushes notifications/message with data.event set to agent_appeared, agent_vanished or tool_call, about once a second. logging/setLevel to warning or above silences it. The relay carries no pushes.

Errors#

What would prove this wrong#

Any tool call that puts bytes into a pane's terminal breaks the server's first rule. So does any answer that describes another window's panes without saying which window it came from.