Skip to main content
Glama
oracle-tmux-mcp

oracle-tmux-mcp

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 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.

Available Tools

7 tools
tmux_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

    A3.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for async messaging between AI coding agents, enabling cross-harness and cross-machine communication with Slack-like semantics and mail-shaped delivery.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for persistent SSH sessions with tmux integration, port forwarding, and SFTP file writes, built for AI agent workflows.
      MIT