Skip to main content
Glama
ketema

tmux-shell

by ketema
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Tmux MCP Shell Tool

An MCP (Model Context Protocol) server that enables AI agents to read tmux pane content on-demand, providing context-aware assistance during interactive terminal sessions.

Problem

AI agents can't see what's happening in your terminal during interactive commands like git rebase -i, vim, or when resolving merge conflicts. This forces you to manually describe your terminal state, breaking your workflow.

Related MCP server: Tmux MCP Server

Solution

This MCP server lets AI agents read your tmux pane content when you ask for help, enabling them to see exactly what you're seeing and provide context-aware guidance.

Key Constraint: LLM input cannot be streamed, so this tool uses a reactive reading approach rather than passive real-time monitoring. The agent only reads your terminal when you explicitly request assistance.

Features

  • On-demand pane reading: AI reads tmux pane content only when you ask

  • Scrollback support: Access terminal history, not just visible content

  • Multi-pane/session support: Target specific tmux sessions, windows, and panes

  • Privacy-focused: No background monitoring, explicit user control

  • Rich metadata: Cursor position, pane dimensions, active command

Installation

npm install -g tmux-mcp-shell-tool

Or use directly with npx:

npx tmux-mcp-shell-tool

Requirements

  • tmux version 2.0 or later

  • Node.js version 18 or later

  • Active tmux session

Quick Start

1. Configure MCP Client

Add to your MCP settings (e.g., Claude Desktop):

{
  "mcpServers": {
    "tmux-shell": {
      "command": "npx",
      "args": ["tmux-mcp-shell-tool"]
    }
  }
}

2. Start Tmux

tmux new-session -s work

3. Use with AI Agent

You: *runs git rebase -i and encounters conflict*
You: "I'm stuck in a rebase with conflicts. Can you help?"
Agent: *uses read_tmux_pane tool*
Agent: "I can see you have a conflict in src/main.rs between lines 45-67.
       The conflict shows your changes vs. the upstream changes..."

MCP Tools

read_tmux_pane

Reads content from a tmux pane.

Parameters:

  • target (string, optional): Tmux target in format session:window.pane (default: current pane)

  • start_line (number, optional): Start line (negative for scrollback, default: visible area)

  • end_line (number, optional): End line (default: end of visible area)

  • include_trailing_spaces (boolean, optional): Preserve trailing spaces (default: false)

Example:

// Read visible area of current pane
{
  "target": null
}

// Read last 100 lines of scrollback
{
  "target": "mysession:1.0",
  "start_line": -100,
  "end_line": -1
}

list_tmux_sessions

Lists all tmux sessions, windows, and panes.

Parameters: None

Returns:

{
  "sessions": [
    {
      "name": "work",
      "windows": [
        {
          "index": 1,
          "name": "editor",
          "panes": [
            {
              "index": 0,
              "command": "vim"
            }
          ]
        }
      ]
    }
  ]
}

Use Cases

Git Rebase Conflicts

User: "I'm in the middle of a rebase and git is showing conflicts"
Agent: *reads pane* "You have conflicts in 2 files: src/app.js and
       config.yaml. Let's resolve them one at a time..."

Vim Navigation

User: "I'm stuck in vim and can't exit"
Agent: *reads pane* "You're in NORMAL mode. Type :q and press Enter to quit,
       or :wq to save and quit"

Debugging Session

User: "The debugger is showing something weird"
Agent: *reads pane* "Looking at your debugger output, the variable 'user'
       is undefined at line 42. This suggests..."

Privacy & Security

What This Tool Does

  • Reads tmux pane content ONLY when AI agent invokes the tool

  • Requires user to actively request help (agent can't read unprompted)

  • Only accesses tmux panes you specify

What This Tool Does NOT Do

  • ❌ Monitor keystrokes in real-time

  • ❌ Run background processes watching your terminal

  • ❌ Automatically filter sensitive data (passwords, API keys)

  • ❌ Store or log terminal content

Best Practices

  1. Be mindful of sensitive data: Avoid asking for help when passwords/keys are visible

  2. Use specific pane targets: Specify exact panes rather than reading all sessions

  3. Review tool invocations: Check what your AI agent is reading in the MCP logs

  4. Clear sensitive content: Clear your terminal or switch panes before requesting help

Architecture

┌─────────────────┐
│   AI Agent      │  User: "I'm stuck in vim"
│  (Claude, etc)  │  Agent: *invokes read_tmux_pane*
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  MCP Server     │  Executes: tmux capture-pane -p
│  (This Tool)    │  Returns: Terminal content
└────────┬────────┘
         │
┌────────▼────────┐
│   Tmux Pane     │  Current content: "-- INSERT --"
│  (User Shell)   │
└─────────────────┘

Concept Document

For detailed architectural decisions and technical rationale, see CONCEPT.md.

Development

# Clone repository
git clone https://github.com/ketema/tmux-mcp-shell-tool.git
cd tmux-mcp-shell-tool

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Test
npm test

Contributing

Contributions welcome! Please read CONCEPT.md to understand the design constraints.

License

MIT

Related

FAQ

Q: Can the AI see my keystrokes in real-time? A: No. The agent only reads pane content when you explicitly ask for help. There's no real-time monitoring.

Q: What if I have sensitive data on screen? A: Clear your screen or switch panes before asking for help. This tool does not filter sensitive data automatically.

Q: Does this work without tmux? A: No. This tool specifically uses tmux's capture capabilities. You must be running tmux.

Q: Can I use this with any AI agent? A: Yes, any agent that supports the Model Context Protocol (MCP) can use this tool.

Q: Why not just use terminal sharing/recording? A: This provides programmatic access for AI agents to read terminal state, enabling context-aware assistance during your workflow without manual copy-paste.

Available Tools

2 tools
list_tmux_sessionsA

Lists all available tmux sessions, windows, and panes. Use this to discover available targets before calling read_tmux_pane.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It implies no side effects by saying 'Lists', but does not explicitly state it is read-only or mention any requirements like tmux being running. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first states the action, the second gives usage guidance. No fluff, front-loaded, and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so the description should explain the format of the returned data (e.g., names, IDs, structure). It says 'lists' but lacks details on what fields are provided. Also missing error conditions or prerequisites like tmux being available.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so schema coverage is 100%. The description adds value by clarifying what exactly is listed (sessions, windows, and panes), beyond just the parameterless schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists tmux sessions, windows, and panes, which is specific and distinguishes it from the sibling tool read_tmux_pane that reads a specific pane.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states to use this tool before calling read_tmux_pane to discover available targets, providing clear guidance on when to use it and implying its role as a prerequisite.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_tmux_paneA

Reads the content of a tmux pane. This enables AI agents to see what is currently displayed in the terminal, providing context-aware assistance during interactive sessions (e.g., git rebase, vim, conflict resolution). The agent only reads the pane when explicitly invoked - there is no background monitoring.

ParametersJSON Schema
NameRequiredDescriptionDefault
targetNoOptional tmux target pane in format "session:window.pane" (e.g., "work:1.0"). If not specified, uses the current pane. You can get available targets using list_tmux_sessions.
end_lineNoOptional ending line number. Use -1 for the last line. If not specified, reads to the end of the visible area.
start_lineNoOptional starting line number. Use negative numbers for scrollback history (e.g., -100 for last 100 lines). If not specified, reads only the visible area.
include_trailing_spacesNoWhether to preserve trailing spaces on each line. Default is false.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It correctly states that reading only occurs on explicit invocation and implies a read-only operation. However, it lacks details on potential side effects, performance implications, or error conditions, making it adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each adding value: action, use case, and invocation guarantee. It is front-loaded with the primary function and contains no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose and usage context well, but with no output schema or annotations, it should clarify the return format (e.g., plain text) and potential errors. The current description is adequate for a simple read tool but lacks completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The tool description adds no extra semantic meaning beyond the schema, such as usage tips or interdependencies. Thus, it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Reads the content of a tmux pane' with a specific verb and resource. It further explains the use case for interactive sessions, and the sibling tool list_tmux_sessions has a distinct purpose (listing sessions, not reading content), so there is no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit context for when to use (interactive sessions like git rebase, vim, conflict resolution) and states no background monitoring. However, it does not explicitly mention when not to use or alternative tools besides the sibling, though the sibling is not a direct alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedlist_tmux_sessions
    • First observedread_tmux_pane
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one lists available sessions/windows/panes, and the other reads the content of a specific pane. There is no overlap or ambiguity.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern: list_tmux_sessions and read_tmux_pane, using snake_case throughout.

Tool Count3/5

With only two tools, the server is on the low end of the appropriate range. While it may serve a narrow read-only use case, it feels thin for a tmux interaction server.

Completeness2/5

The server lacks essential tools for writing commands, managing sessions (create, attach, close), or any interactive control. This is a significant gap for a terminal-focused server.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • Tmux MCP Server

    nickgnd
    A
    license
    A
    quality
    F
    maintenance
    Enables Claude Desktop to interact with and view tmux session content, allowing AI assistants to read from, control, and observe terminal sessions.
    13
    211 npm
    301
    MIT

  • Tmux MCP Server

    audibleblink
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to manage local tmux sessions, including creating and controlling sessions, windows, and panes, sending commands, and capturing terminal output.
    16
    10 npm
    Do What The F*ck You Want To Public

  • tmux-bridge-mcp

    howardpen9
    A
    license
    A
    quality
    C
    maintenance
    Enables AI agents to communicate and coordinate across tmux panes, allowing them to read, type, and send messages to each other without manual copy-pasting.
    9
    25 npm
    99
    MIT

  • tmux-mcp

    WENLIXIAO-CS
    A
    license
    A
    quality
    D
    maintenance
    Allows AI assistants to create, manage, and interact with tmux sessions, windows, and panes programmatically.
    19
    MIT