oracle-tmux-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oracle-tmux-mcp send hello to agent alpha"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
oracle-tmux-mcp
MCP server that gives AI agents a live, tmux-backed messaging mesh: every agent gets its own tmux pane, and messages appear there instantly — no polling, no manual "check my messages" round trip.
Why this exists
oracle-messages (the file-backed message bus) requires the recipient to
poll (peer list, peer monitor) or call sync_messages to discover new
messages. This server flips that: tmux_send/tmux_broadcast push the
message into the recipient's tmux pane the moment they're called, so a
human (or another process) watching that pane sees it land live.
Message data is still properly managed, not just printed to a terminal:
every send is recorded to a per-agent JSONL log (tmux_history queries it),
and the tmux pane is just a live view of the same underlying data.
Related MCP server: mcp-ssh-interactive
Tools
tmux_register_agent(name)— pre-create an agent's pane (optional; send/broadcast self-provision)tmux_send(from, to, body)— deliver to one agent, shows up instantlytmux_broadcast(from, body)— deliver to every registered agenttmux_list_agents()— rostertmux_history(agent, limit?)— structured message history (the source of truth)tmux_attach_info(agent)— the shell command to attach a terminal directly to that agent's pane
Requirements
Node 20+
tmux— on Windows, via WSL (wsl --install, thensudo apt install tmuxinside it)
Setup
npm install
npm run buildRegister with an MCP client (e.g. Claude Code)
Add to .mcp.json:
{
"mcpServers": {
"oracle-tmux": {
"command": "node",
"args": ["D:/Projects/Github/Oracle-Ecosystems/Oracle-tmux-mcp/dist/index.js"]
}
}
}Env
ORACLE_TMUX_SESSION— tmux session name (defaultoracle)ORACLE_TMUX_DISTRO— WSL distro name, Windows only (defaultUbuntu)ORACLE_TMUX_MCP_DIR— where mailbox/history files live (default~/.oracle-tmux-mcp/mail)ORACLE_TMUX_WATCH_SCRIPT— override path toscripts/watch.sh
How the live pane actually works
Each pane runs scripts/watch.sh <agent> <mailbox-file>, a small polling
loop (300ms) that prints newly-appended bytes. This is deliberately not
tail -F: this server runs on Windows and writes via Node's fs, while the
tmux pane runs inside WSL reading the same file over the DrvFs /mnt/c/...
mount. WSL2's DrvFs does not reliably fire inotify events for changes made
from the Windows side, so tail -F picks up whatever's in the file at
attach time but silently misses every append after that (confirmed by
testing). A dumb byte-offset poll sidesteps inotify entirely and is correct
regardless of which side writes.
Watch a conversation
wsl.exe -d Ubuntu -- tmux attach -t oracle # see all agents' panes, Ctrl-b w to switchOr use the exact command tmux_attach_info returns for one agent.
Available Tools
7 toolstmux_attach_infoGet attach commandA
Get the shell command a human can run to attach a terminal directly to one agent's live pane.
Inputs: agent (required).
tmux_broadcastBroadcast messageC
Send a message to every registered agent (except the sender). Each recipient's pane updates instantly.
Inputs: body (required), from (required).
tmux_historyGet message historyA
Fetch an agent's structured message history (source of truth — the tmux pane is just a live view of the same data).
Inputs: agent (required), limit.
tmux_list_agentsList agentsA
List every agent registered in the mesh.
Inputs: no named parameters.
tmux_open_claudeOpen live Claude chat paneA
Spawn an interactive Claude Code session in a tmux pane as the given agent. From then on, tmux_send to that agent types the message directly into that chat — it appears on screen and Claude responds, no polling and no human input.
Inputs: agent (required).
tmux_register_agentRegister agentB
Register an agent and ensure its live tmux pane exists. Not required before send/broadcast — they self-provision — but useful to pre-create a pane before anyone messages that agent.
Inputs: name (required).
tmux_sendSend messageB
Send a message to one agent. Appears instantly in the recipient's tmux pane (push-based, no polling) and is recorded in their queryable history.
Inputs: to (required), body (required), from (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a clearly distinct operation: registration, unicast, broadcast, listing, history, interactive session spawning, and attach info. There is no meaningful overlap or confusion between any two tools.
All tools follow a consistent tmux_verb_noun pattern (tmux_register_agent, tmux_send, tmux_broadcast, tmux_list_agents). The naming convention is uniform and predictable throughout.
Seven tools is a well-scoped set for a messaging/orchestration mesh. Each tool earns its place, covering registration, messaging (unicast/broadcast), introspection, interactive session management, and operational info.
The surface covers the core lifecycle well: register, message, broadcast, list, view history, and open interactive sessions. Minor gaps exist (no explicit unregister/deregister or kill-session tool), but agents can still operate without these.
Related MCP Connectors
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Messaging network for AI agents: talk to other people's agents over MCP. Free forever.
Remote MCP server for The Colony — a social network for AI agents (posts, DMs, search, marketplace).
MCP server for AI agents: posts, messages and comments on WhatsApp, Instagram, TikTok and Facebook.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceOpen-source MCP server for collaborative AI agents, providing a shared mailbox, identity model, and notification fabric.276 npm3Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server that enables AI agents to run fully interactive SSH sessions (via tmux) and execute commands like a human operator, with persistent sessions and multiple concurrent connections.6MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for async messaging between AI coding agents, enabling cross-harness and cross-machine communication with Slack-like semantics and mail-shaped delivery.2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for persistent SSH sessions with tmux integration, port forwarding, and SFTP file writes, built for AI agent workflows.MIT