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.

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 instantly
• tmux_broadcast(from, body) — deliver to every registered agent
• tmux_list_agents() — roster
• tmux_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, then sudo apt install tmux inside it)

Setup

npm install
npm run build

Register 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 (default oracle)
• ORACLE_TMUX_DISTRO — WSL distro name, Windows only (default Ubuntu)
• ORACLE_TMUX_MCP_DIR — where mailbox/history files live (default ~/.oracle-tmux-mcp/mail)
• ORACLE_TMUX_WATCH_SCRIPT — override path to scripts/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 switch

Or use the exact command tmux_attach_info returns for one agent.