tmuxer

An MCP server for managing background jobs via tmux sessions where you can watch your LLM's jobs in real-time.

Why tmuxer?

When LLM clients run commands, you usually need a few interactions to see the full command, and output is often delayed or truncated. tmuxer gives you:

• Watch jobs live - Attach to see command output in real-time as the LLM works
• Browse all jobs - Window picker lets you flip between running processes
• Full terminal support - Tools like npm, docker, and htop render correctly
• Interactive input - Send keystrokes to running jobs (e.g., Ctrl+C to stop, or respond to prompts)
• Auto-cleanup - Jobs are killed when the process exits by default, or set keepAlive to persist beyond mcp lifetime

Installation

npm install tmuxer

Usage

Add to your MCP configuration:

{
  "mcpServers": {
    "tmuxer": {
      "command": "npx",
      "args": ["-y", "tmuxer"]
    }
  }
}

Run npx tmuxer --help to see available CLI flags.

MCP Tools

| Tool | Description | | -------------- | --------------------------------------------------------------------------------------------------------- | | createJob | Start a command in a background tmux window. Set keepAlive: true to persist after process exit | | listJobs | List all jobs with status (running, pid, exitCode) | | getJobOutput | Get terminal output (supports lastLines for recent output only) | | sendInput | Send keystrokes or text to a job (use {C-c} for Ctrl+C, {Up} for up arrow, {Enter} for enter, etc.) | | cleanupJobs | Remove dead job windows (skips running jobs) |

Example workflow

1. createJob({ command: "npm run dev", prefix: "dev", keepAlive: true })  // returns jobId: "dev1"
2. listJobs({})  // check status, pid, running state
3. getJobOutput({ jobId: "dev1", lastLines: 20 })  // see recent logs
4. sendInput({ jobId: "dev1", input: "{C-c}" })  // stop the server

Programmatic usage

You can run processes in the MCP session programmatically:

import { createJob } from 'tmuxer';

const { jobId } = await createJob({ command: 'npm run dev' });

Spectating

Run this in your terminal to attach to the tmuxer session with a list of running jobs:

tmux attach ';' choose-tree

You can use the up/down arrow keys to browse running jobs and see their live output in the preview pane. Press Enter to select a job and view it full screen.

• Ctrl+b then d disconnects from tmux
• Ctrl+b then w Goes back to the picker view.

If you see "no sessions", it means the MCP server hasn't connected yet.

It may be helpful to brush up on basic tmux commands if you're not familiar with tmux.

Demos

Nested tmux support

Commands that spawn their own tmux sessions work seamlessly—tmuxer unsets the TMUX environment variable so nested sessions work correctly.

Use cases

• Dev servers - Start npm run dev and check logs without blocking
• Builds - Run npm run build and poll for completion
• Tests - Run test suites and retrieve results when done
• Interactive tools - Handle tools that need input (setup wizards like npm init, create-vite, git rebase -i, etc.)
• Monitoring - Check on processes with complex terminal UIs (docker, htop, etc.)

Development

npm test        # run tests
npm run build   # compile typescript

License

MIT