# 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

```bash
npm install
npm run build
```

## Register with an MCP client (e.g. Claude Code)

Add to `.mcp.json`:

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

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