oracle-tmux-mcp

oracle-tmux-mcp

MCP server that gives AI agents a live, tmux-backed messaging mesh: everyagent gets its own tmux pane, and messages appear there instantly — nopolling, no manual "check my messages" round trip.

Why this exists

oracle-messages (the file-backed message bus) requires the recipient topoll (peer list, peer monitor) or call sync_messages to discover newmessages. This server flips that: tmux_send/tmux_broadcast push themessage into the recipient's tmux pane the moment they're called, so ahuman (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 pollingloop (300ms) that prints newly-appended bytes. This is deliberately nottail -F: this server runs on Windows and writes via Node's fs, while thetmux 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 madefrom the Windows side, so tail -F picks up whatever's in the file atattach time but silently misses every append after that (confirmed bytesting). A dumb byte-offset poll sidesteps inotify entirely and is correctregardless 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.