mcp-terminal-share
mcp-terminal-share
An MCP server that lets two or more Claude Code terminals on the same machine talk to each other. Register each terminal with a short name, then send messages between them.
┌──────────────┐ ┌──────────────┐
│ terminal A │ ── send_message ──► │ terminal B │
│ │ ◄── send_message ── │ │
└──────────────┘ └──────────────┘
│ file-based │
└──────► ~/.claude/terminal-messages ──┘Why
Pair-running two Claude Code sessions and want one to hand off a long log or a task summary to the other? That's it.
Related MCP server: claude-intercom-mcp
Install
Wire it into Claude Code's MCP config (Claude Code → ~/.claude.json or via the CLI):
claude mcp add terminal-share -- npx -y mcp-terminal-shareOr by hand in your MCP config:
{
"mcpServers": {
"terminal-share": {
"command": "npx",
"args": ["-y", "mcp-terminal-share"]
}
}
}Requires Node.js 18+.
Tools
Tool | Purpose |
| Give this terminal a name (e.g. |
| Show all live terminals. Stale records are cleaned up automatically. |
| Send |
| Read messages addressed to you. Deletes them on read by default. |
| Block until a message arrives or |
Names must match ^[A-Za-z0-9_-]{1,32}$. Message content is capped at 1 MB, summary at 500 B.
Suggested slash commands
If you already use the bundled t-rg / t-list / t-send / t-get / t-watch skills, they map 1:1 onto the tools above.
Show the registered name in your statusline
After a successful register, the server writes a tiny session record keyed by a hash of the working directory:
~/.claude/terminal-messages/sessions/<sha256(cwd)[:16]>.jsonThe MCP server, your statusline, and any helper subprocess it spawns all inherit cwd from the same Claude Code session, so they can find each other without any extra plumbing.
claude-hud
Add --extra-cmd "mcp-terminal-share-label" to your statusline command:
{
"statusLine": {
"type": "command",
"command": "claude-hud --extra-cmd \"mcp-terminal-share-label\""
}
}The bundled mcp-terminal-share-label bin reads the record for the current cwd and outputs claude-hud's expected {"label": "📟 <name>"} (or {} when nothing is registered). Override the emoji/prefix with MCP_TERMINAL_SHARE_LABEL_PREFIX.
Other statuslines
Roll your own. The minimal Node version:
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";
import { createHash } from "node:crypto";
const key = createHash("sha256").update(process.cwd()).digest("hex").slice(0, 16);
try {
const { name } = JSON.parse(
readFileSync(
join(homedir(), ".claude", "terminal-messages", "sessions", `${key}.json`),
"utf-8",
),
);
process.stdout.write(`📟 ${name}`);
} catch {
// not registered
}The file is removed automatically when the MCP server shuts down.
Known limitation: if you open two Claude Code sessions in the same directory, the later one's register overwrites the earlier one's session record. This only affects the statusline label — message routing between terminals is unaffected.
How it works
Each terminal writes its registration to
~/.claude/terminal-messages/terminals/<name>.json.Messages are dropped into
~/.claude/terminal-messages/messages/to_<recipient>_<ts>_<rand>.json.A session record for statusline consumers lives at
~/.claude/terminal-messages/sessions/<sha256(cwd)[:16]>.json.Liveness uses a 5 s heartbeat; records older than 30 s whose owning PID is also dead are reaped on read.
Messages older than 24 h are reaped on read, and a per-recipient queue cap of 100 prevents runaway buildup.
All file writes go through a temp-file + rename for atomicity.
Override the storage root with MCP_TERMINAL_SHARE_DIR (mostly useful for tests).
Security model
Local, single-user, single-host. Anyone with read access to
~/.claude/terminal-messagescan read or spoof messages. This is fine on a personal dev machine and explicitly out of scope to defend otherwise.No network surface. Communication is purely through the local filesystem; nothing listens on a port.
Input validation. Names are regex-validated to prevent path traversal; content size is capped.
If you need cross-machine sharing or untrusted multi-tenant isolation, this is the wrong tool — reach for a real message bus.
Development
npm install
npm testTests use Node's built-in node:test runner with isolated temp dirs (no extra deps).
License
Available Tools
5 toolsget_messagesA
Read messages sent to this terminal. Returns all messages and optionally deletes them after reading.
Inputs: terminal_name (required), delete_after_read.
list_terminalsB
List all registered terminals.
Inputs: no named parameters.
registerA
Register this terminal with a name (e.g. A1, A2). Other terminals can then send messages to this name.
Inputs: name (required).
send_messageB
Send a message to another terminal. The target terminal can read it with get_messages.
Inputs: from (required), to (required), summary (required), content (required).
watch_messagesA
Block and wait for a message to arrive for this terminal. Returns as soon as a message is received or timeout is reached.
Inputs: terminal_name (required), timeout, interval.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear, non-overlapping purpose: registration, sending, listing, and two distinct reading methods (polling and blocking). No ambiguity.
All tool names follow a consistent verb_noun pattern (get_messages, list_terminals, register, send_message, watch_messages), making them predictable.
With 5 tools covering the core operations of a terminal messaging service, the count is well-scoped and each tool earns its place.
The tool surface covers registration, sending, and two receive modes. A minor gap is the lack of an explicit unregister or delete functionality, but the core workflow is complete.
Related MCP Connectors
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Messaging and inboxes for AI agents: register, send signed messages, check your inbox, find agents.
Ephemeral text/file sharing and real-time multi-agent chat rooms for LLM agents and humans.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables file-based agent-to-agent communication between Claude Code instances on the same machine, using MCP channels and plain JSON files.5 npm15MIT
- AlicenseAqualityCmaintenanceEnables local messaging between Claude Code, Codex, Pi, and other coding-agent sessions on the same machine, allowing them to discover each other, send updates, ask questions, and reply.819 npm3AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables local agent-to-agent messaging between Claude Code sessions via file-based channels, with a registry, MCP tools and CLI for sending, reading, and tracking messages.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables real-time, file-based messaging between terminal AI agents (like Claude Code, Gemini CLI) allowing them to collaborate on tasks directly without a server or network, using JSON files and atomic rename for coordination.16 PyPIMIT