@arearseth/tmux-mcp 0.2.2

package/LICENSE.md

@@ -0,0 +1,8 @@
+Copyright 2025 Nicolò Gnudi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,77 @@
+# Tmux MCP Server
+
+Model Context Protocol server that enables Claude Desktop to interact with and view tmux session content. This integration allows AI assistants to read from, control, and observe your terminal sessions.
+
+## Features
+
+- List and search tmux sessions
+- View and navigate tmux windows and panes
+- Capture and expose terminal content from any pane
+- Execute commands in tmux panes and retrieve results (use it at your own risk ⚠️)
+- Create new tmux sessions and windows
+- Split panes horizontally or vertically with customizable sizes
+- Kill tmux sessions, windows, and panes
+
+Check out this short video to get excited!
+
+</br>
+
+[![youtube video](http://i.ytimg.com/vi/3W0pqRF1RS0/hqdefault.jpg)](https://www.youtube.com/watch?v=3W0pqRF1RS0)
+
+## Prerequisites
+
+- Node.js
+- tmux installed and running
+
+## Usage
+
+### Configure Claude Desktop
+
+Add this MCP server to your Claude Desktop configuration:
+
+```json
+"mcpServers": {
+  "tmux": {
+    "command": "npx",
+    "args": ["-y", "tmux-mcp"]
+  }
+}
+```
+
+### MCP server options
+
+You can optionally specify the command line shell you are using, if unspecified it defaults to `bash`
+
+```json
+"mcpServers": {
+  "tmux": {
+    "command": "npx",
+    "args": ["-y", "tmux-mcp", "--shell-type=fish"]
+  }
+}
+```
+
+The MCP server needs to know the shell only when executing commands, to properly read its exit status.
+
+## Available Resources
+
+- `tmux://sessions` - List all tmux sessions
+- `tmux://pane/{paneId}` - View content of a specific tmux pane
+- `tmux://command/{commandId}/result` - Results from executed commands
+
+## Available Tools
+
+- `list-sessions` - List all active tmux sessions
+- `find-session` - Find a tmux session by name
+- `list-windows` - List windows in a tmux session
+- `list-panes` - List panes in a tmux window
+- `capture-pane` - Capture content from a tmux pane
+- `create-session` - Create a new tmux session
+- `create-window` - Create a new window in a tmux session
+- `split-pane` - Split a tmux pane horizontally or vertically with optional size
+- `kill-session` - Kill a tmux session by ID
+- `kill-window` - Kill a tmux window by ID
+- `kill-pane` - Kill a tmux pane by ID
+- `execute-command` - Execute a command in a tmux pane
+- `get-command-result` - Get the result of an executed command
+

package/build/index.js

@@ -0,0 +1,567 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import * as tmux from "./tmux.js";
+// Create MCP server
+const server = new McpServer({
+    name: "tmux-mcp",
+    version: "0.2.2"
+}, {
+    capabilities: {
+        resources: {
+            subscribe: true,
+            listChanged: true
+        },
+        tools: {
+            listChanged: true
+        },
+        logging: {}
+    }
+});
+const shellTypeSchema = z.enum(tmux.supportedShellTypes);
+// List all tmux sessions - Tool
+server.tool("list-sessions", "List all active tmux sessions", {}, async () => {
+    try {
+        const sessions = await tmux.listSessions();
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(sessions, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error listing tmux sessions: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Find session by name - Tool
+server.tool("find-session", "Find a tmux session by name", {
+    name: z.string().describe("Name of the tmux session to find")
+}, async ({ name }) => {
+    try {
+        const session = await tmux.findSessionByName(name);
+        return {
+            content: [{
+                    type: "text",
+                    text: session ? JSON.stringify(session, null, 2) : `Session not found: ${name}`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error finding tmux session: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// List windows in a session - Tool
+server.tool("list-windows", "List windows in a tmux session", {
+    sessionId: z.string().describe("ID of the tmux session")
+}, async ({ sessionId }) => {
+    try {
+        const windows = await tmux.listWindows(sessionId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(windows, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error listing windows: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// List panes in a window - Tool
+server.tool("list-panes", "List panes in a tmux window", {
+    windowId: z.string().describe("ID of the tmux window")
+}, async ({ windowId }) => {
+    try {
+        const panes = await tmux.listPanes(windowId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(panes, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error listing panes: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Capture pane content - Tool
+server.tool("capture-pane", "Capture content from a tmux pane with configurable lines count and optional color preservation", {
+    paneId: z.string().describe("ID of the tmux pane"),
+    lines: z.string().optional().describe("Number of lines to capture"),
+    colors: z.boolean().optional().describe("Include color/escape sequences for text and background attributes in output")
+}, async ({ paneId, lines, colors }) => {
+    try {
+        // Parse lines parameter if provided
+        const linesCount = lines ? parseInt(lines, 10) : undefined;
+        const includeColors = colors || false;
+        const content = await tmux.capturePaneContent(paneId, linesCount, includeColors);
+        return {
+            content: [{
+                    type: "text",
+                    text: content || "No content captured"
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error capturing pane content: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Create new session - Tool
+server.tool("create-session", "Create a new tmux session", {
+    name: z.string().describe("Name for the new tmux session")
+}, async ({ name }) => {
+    try {
+        const session = await tmux.createSession(name);
+        return {
+            content: [{
+                    type: "text",
+                    text: session
+                        ? `Session created: ${JSON.stringify(session, null, 2)}`
+                        : `Failed to create session: ${name}`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error creating session: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Create new window - Tool
+server.tool("create-window", "Create a new window in a tmux session", {
+    sessionId: z.string().describe("ID of the tmux session"),
+    name: z.string().describe("Name for the new window")
+}, async ({ sessionId, name }) => {
+    try {
+        const window = await tmux.createWindow(sessionId, name);
+        return {
+            content: [{
+                    type: "text",
+                    text: window
+                        ? `Window created: ${JSON.stringify(window, null, 2)}`
+                        : `Failed to create window: ${name}`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error creating window: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Kill session - Tool
+server.tool("kill-session", "Kill a tmux session by ID", {
+    sessionId: z.string().describe("ID of the tmux session to kill")
+}, async ({ sessionId }) => {
+    try {
+        await tmux.killSession(sessionId);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Session ${sessionId} has been killed`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error killing session: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Kill window - Tool
+server.tool("kill-window", "Kill a tmux window by ID", {
+    windowId: z.string().describe("ID of the tmux window to kill")
+}, async ({ windowId }) => {
+    try {
+        await tmux.killWindow(windowId);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Window ${windowId} has been killed`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error killing window: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Kill pane - Tool
+server.tool("kill-pane", "Kill a tmux pane by ID", {
+    paneId: z.string().describe("ID of the tmux pane to kill")
+}, async ({ paneId }) => {
+    try {
+        await tmux.killPane(paneId);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Pane ${paneId} has been killed`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error killing pane: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Split pane - Tool
+server.tool("split-pane", "Split a tmux pane horizontally or vertically", {
+    paneId: z.string().describe("ID of the tmux pane to split"),
+    direction: z.enum(["horizontal", "vertical"]).optional().describe("Split direction: 'horizontal' (side by side) or 'vertical' (top/bottom). Default is 'vertical'"),
+    size: z.number().min(1).max(99).optional().describe("Size of the new pane as percentage (1-99). Default is 50%")
+}, async ({ paneId, direction, size }) => {
+    try {
+        const newPane = await tmux.splitPane(paneId, direction || 'vertical', size);
+        return {
+            content: [{
+                    type: "text",
+                    text: newPane
+                        ? `Pane split successfully. New pane: ${JSON.stringify(newPane, null, 2)}`
+                        : `Failed to split pane ${paneId}`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error splitting pane: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Configure shell type - Tool
+server.tool("set-shell-type", "Configure the shell type used for command execution. Provide paneId to override a specific pane.", {
+    type: shellTypeSchema,
+    paneId: z.string().optional().describe("ID of the tmux pane to override. Omit to change the default shell type.")
+}, async ({ type, paneId }) => {
+    try {
+        tmux.setShellConfig({ type, paneId });
+        const target = paneId ? `pane ${paneId}` : 'default';
+        return {
+            content: [{
+                    type: "text",
+                    text: `Shell type for ${target} set to ${type}`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error setting shell type: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Execute command in pane - Tool
+server.tool("execute-command", "Execute a command in a tmux pane and get results. For interactive applications (REPLs, editors), use `rawMode=true`. IMPORTANT: When `rawMode=false` (default), avoid heredoc syntax (cat << EOF) and other multi-line constructs as they conflict with command wrapping. For file writing, prefer: printf 'content\\n' > file, echo statements, or write to temp files instead", {
+    paneId: z.string().describe("ID of the tmux pane"),
+    command: z.string().describe("Command to execute"),
+    rawMode: z.boolean().optional().describe("Execute command without wrapper markers for REPL/interactive compatibility. Disables get-command-result status tracking. Use capture-pane after execution to verify command outcome."),
+    noEnter: z.boolean().optional().describe("Send keystrokes without pressing Enter. For TUI navigation in apps like btop, vim, less. Supports special keys (Up, Down, Escape, Tab, etc.) and strings (sent char-by-char for proper filtering). Automatically applies rawMode. Use capture-pane after to see results.")
+}, async ({ paneId, command, rawMode, noEnter }) => {
+    try {
+        // If noEnter is true, automatically apply rawMode
+        const effectiveRawMode = noEnter || rawMode;
+        const commandId = await tmux.executeCommand(paneId, command, effectiveRawMode, noEnter);
+        if (effectiveRawMode) {
+            const modeText = noEnter ? "Keys sent without Enter" : "Interactive command started (rawMode)";
+            return {
+                content: [{
+                        type: "text",
+                        text: `${modeText}.\n\nStatus tracking is disabled.\nUse 'capture-pane' with paneId '${paneId}' to verify the command outcome.\n\nCommand ID: ${commandId}`
+                    }]
+            };
+        }
+        // Create the resource URI for this command's results
+        const resourceUri = `tmux://command/${commandId}/result`;
+        return {
+            content: [{
+                    type: "text",
+                    text: `Command execution started.\n\nTo get results, subscribe to and read resource: ${resourceUri}\n\nStatus will change from 'pending' to 'completed' or 'error' when finished.`
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error executing command: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Get command result - Tool
+server.tool("get-command-result", "Get the result of an executed command", {
+    commandId: z.string().describe("ID of the executed command")
+}, async ({ commandId }) => {
+    try {
+        // Check and update command status
+        const command = await tmux.checkCommandStatus(commandId);
+        if (!command) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Command not found: ${commandId}`
+                    }],
+                isError: true
+            };
+        }
+        // Format the response based on command status
+        let resultText;
+        if (command.status === 'pending') {
+            if (command.result) {
+                resultText = `Status: ${command.status}\nCommand: ${command.command}\n\n--- Message ---\n${command.result}`;
+            }
+            else {
+                resultText = `Command still executing...\nStarted: ${command.startTime.toISOString()}\nCommand: ${command.command}`;
+            }
+        }
+        else {
+            resultText = `Status: ${command.status}\nExit code: ${command.exitCode}\nCommand: ${command.command}\n\n--- Output ---\n${command.result}`;
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: resultText
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error retrieving command result: ${error}`
+                }],
+            isError: true
+        };
+    }
+});
+// Expose tmux session list as a resource
+server.resource("Tmux Sessions", "tmux://sessions", async () => {
+    try {
+        const sessions = await tmux.listSessions();
+        return {
+            contents: [{
+                    uri: "tmux://sessions",
+                    text: JSON.stringify(sessions.map(session => ({
+                        id: session.id,
+                        name: session.name,
+                        attached: session.attached,
+                        windows: session.windows
+                    })), null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            contents: [{
+                    uri: "tmux://sessions",
+                    text: `Error listing tmux sessions: ${error}`
+                }]
+        };
+    }
+});
+// Expose pane content as a resource
+server.resource("Tmux Pane Content", new ResourceTemplate("tmux://pane/{paneId}", {
+    list: async () => {
+        try {
+            // Get all sessions
+            const sessions = await tmux.listSessions();
+            const paneResources = [];
+            // For each session, get all windows
+            for (const session of sessions) {
+                const windows = await tmux.listWindows(session.id);
+                // For each window, get all panes
+                for (const window of windows) {
+                    const panes = await tmux.listPanes(window.id);
+                    // For each pane, create a resource with descriptive name
+                    for (const pane of panes) {
+                        paneResources.push({
+                            name: `Pane: ${session.name} - ${pane.id} - ${pane.title} ${pane.active ? "(active)" : ""}`,
+                            uri: `tmux://pane/${pane.id}`,
+                            description: `Content from pane ${pane.id} - ${pane.title} in session ${session.name}`
+                        });
+                    }
+                }
+            }
+            return {
+                resources: paneResources
+            };
+        }
+        catch (error) {
+            server.server.sendLoggingMessage({
+                level: 'error',
+                data: `Error listing panes: ${error}`
+            });
+            return { resources: [] };
+        }
+    }
+}), async (uri, { paneId }) => {
+    try {
+        // Ensure paneId is a string
+        const paneIdStr = Array.isArray(paneId) ? paneId[0] : paneId;
+        // Default to no colors for resources to maintain clean programmatic access
+        const content = await tmux.capturePaneContent(paneIdStr, 200, false);
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: content || "No content captured"
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Error capturing pane content: ${error}`
+                }]
+        };
+    }
+});
+// Create dynamic resource for command executions
+server.resource("Command Execution Result", new ResourceTemplate("tmux://command/{commandId}/result", {
+    list: async () => {
+        // Only list active commands that aren't too old
+        tmux.cleanupOldCommands(10); // Clean commands older than 10 minutes
+        const resources = [];
+        for (const id of tmux.getActiveCommandIds()) {
+            const command = tmux.getCommand(id);
+            if (command) {
+                resources.push({
+                    name: `Command: ${command.command.substring(0, 30)}${command.command.length > 30 ? '...' : ''}`,
+                    uri: `tmux://command/${id}/result`,
+                    description: `Execution status: ${command.status}`
+                });
+            }
+        }
+        return { resources };
+    }
+}), async (uri, { commandId }) => {
+    try {
+        // Ensure commandId is a string
+        const commandIdStr = Array.isArray(commandId) ? commandId[0] : commandId;
+        // Check command status
+        const command = await tmux.checkCommandStatus(commandIdStr);
+        if (!command) {
+            return {
+                contents: [{
+                        uri: uri.href,
+                        text: `Command not found: ${commandIdStr}`
+                    }]
+            };
+        }
+        // Format the response based on command status
+        let resultText;
+        if (command.status === 'pending') {
+            // For rawMode commands, we set a result message while status remains 'pending'
+            // since we can't track their actual completion
+            if (command.result) {
+                resultText = `Status: ${command.status}\nCommand: ${command.command}\n\n--- Message ---\n${command.result}`;
+            }
+            else {
+                resultText = `Command still executing...\nStarted: ${command.startTime.toISOString()}\nCommand: ${command.command}`;
+            }
+        }
+        else {
+            resultText = `Status: ${command.status}\nExit code: ${command.exitCode}\nCommand: ${command.command}\n\n--- Output ---\n${command.result}`;
+        }
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: resultText
+                }]
+        };
+    }
+    catch (error) {
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Error retrieving command result: ${error}`
+                }]
+        };
+    }
+});
+async function main() {
+    try {
+        const { values } = parseArgs({
+            options: {
+                'shell-type': { type: 'string', default: 'bash', short: 's' }
+            }
+        });
+        // Set shell configuration
+        tmux.setShellConfig({
+            type: values['shell-type']
+        });
+        // Start the MCP server
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    catch (error) {
+        console.error("Failed to start MCP server:", error);
+        process.exit(1);
+    }
+}
+main().catch(error => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/build/tmux.js

@@ -0,0 +1,352 @@
+import { exec as execCallback } from "child_process";
+import { promisify } from "util";
+import { v4 as uuidv4 } from 'uuid';
+const exec = promisify(execCallback);
+export const supportedShellTypes = ['bash', 'zsh', 'fish', 'fc_shell'];
+const shellConfig = {
+    defaultType: 'bash',
+    paneOverrides: new Map()
+};
+function normalizeShellType(type) {
+    return supportedShellTypes.includes(type)
+        ? type
+        : 'bash';
+}
+export function setShellConfig(config) {
+    const normalized = normalizeShellType(config.type);
+    if (config.paneId) {
+        shellConfig.paneOverrides.set(config.paneId, normalized);
+        // Reset cached initialization so the helper can be installed on demand
+        fcShellInitializedPanes.delete(config.paneId);
+        return;
+    }
+    shellConfig.defaultType = normalized;
+    if (normalized !== 'fc_shell') {
+        fcShellInitializedPanes.clear();
+    }
+}
+function resolveShellType(paneId) {
+    return shellConfig.paneOverrides.get(paneId) ?? shellConfig.defaultType;
+}
+/**
+ * Execute a tmux command and return the result
+ */
+export async function executeTmux(tmuxCommand) {
+    try {
+        const { stdout } = await exec(`tmux ${tmuxCommand}`);
+        return stdout.trim();
+    }
+    catch (error) {
+        throw new Error(`Failed to execute tmux command: ${error.message}`);
+    }
+}
+/**
+ * Check if tmux server is running
+ */
+export async function isTmuxRunning() {
+    try {
+        await executeTmux("list-sessions -F '#{session_name}'");
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * List all tmux sessions
+ */
+export async function listSessions() {
+    const format = "#{session_id}:#{session_name}:#{?session_attached,1,0}:#{session_windows}";
+    const output = await executeTmux(`list-sessions -F '${format}'`);
+    if (!output)
+        return [];
+    return output.split('\n').map(line => {
+        const [id, name, attached, windows] = line.split(':');
+        return {
+            id,
+            name,
+            attached: attached === '1',
+            windows: parseInt(windows, 10)
+        };
+    });
+}
+/**
+ * Find a session by name
+ */
+export async function findSessionByName(name) {
+    try {
+        const sessions = await listSessions();
+        return sessions.find(session => session.name === name) || null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * List windows in a session
+ */
+export async function listWindows(sessionId) {
+    const format = "#{window_id}:#{window_name}:#{?window_active,1,0}";
+    const output = await executeTmux(`list-windows -t '${sessionId}' -F '${format}'`);
+    if (!output)
+        return [];
+    return output.split('\n').map(line => {
+        const [id, name, active] = line.split(':');
+        return {
+            id,
+            name,
+            active: active === '1',
+            sessionId
+        };
+    });
+}
+/**
+ * List panes in a window
+ */
+export async function listPanes(windowId) {
+    const format = "#{pane_id}:#{pane_title}:#{?pane_active,1,0}";
+    const output = await executeTmux(`list-panes -t '${windowId}' -F '${format}'`);
+    if (!output)
+        return [];
+    return output.split('\n').map(line => {
+        const [id, title, active] = line.split(':');
+        return {
+            id,
+            windowId,
+            title: title,
+            active: active === '1'
+        };
+    });
+}
+/**
+ * Capture content from a specific pane, by default the latest 200 lines.
+ */
+export async function capturePaneContent(paneId, lines = 200, includeColors = false) {
+    const colorFlag = includeColors ? '-e' : '';
+    return executeTmux(`capture-pane -p ${colorFlag} -t '${paneId}' -S -${lines} -E -`);
+}
+/**
+ * Create a new tmux session
+ */
+export async function createSession(name) {
+    await executeTmux(`new-session -d -s "${name}"`);
+    return findSessionByName(name);
+}
+/**
+ * Create a new window in a session
+ */
+export async function createWindow(sessionId, name) {
+    const output = await executeTmux(`new-window -t '${sessionId}' -n '${name}'`);
+    const windows = await listWindows(sessionId);
+    return windows.find(window => window.name === name) || null;
+}
+/**
+ * Kill a tmux session by ID
+ */
+export async function killSession(sessionId) {
+    await executeTmux(`kill-session -t '${sessionId}'`);
+}
+/**
+ * Kill a tmux window by ID
+ */
+export async function killWindow(windowId) {
+    await executeTmux(`kill-window -t '${windowId}'`);
+}
+/**
+ * Kill a tmux pane by ID
+ */
+export async function killPane(paneId) {
+    await executeTmux(`kill-pane -t '${paneId}'`);
+}
+/**
+ * Split a tmux pane horizontally or vertically
+ */
+export async function splitPane(targetPaneId, direction = 'vertical', size) {
+    // Build the split-window command
+    let splitCommand = 'split-window';
+    // Add direction flag (-h for horizontal, -v for vertical)
+    if (direction === 'horizontal') {
+        splitCommand += ' -h';
+    }
+    else {
+        splitCommand += ' -v';
+    }
+    // Add target pane
+    splitCommand += ` -t '${targetPaneId}'`;
+    // Add size if specified (as percentage)
+    if (size !== undefined && size > 0 && size < 100) {
+        splitCommand += ` -p ${size}`;
+    }
+    // Execute the split command
+    await executeTmux(splitCommand);
+    // Get the window ID from the target pane to list all panes
+    const windowInfo = await executeTmux(`display-message -p -t '${targetPaneId}' '#{window_id}'`);
+    // List all panes in the window to find the newly created one
+    const panes = await listPanes(windowInfo);
+    // The newest pane is typically the last one in the list
+    return panes.length > 0 ? panes[panes.length - 1] : null;
+}
+// Map to track ongoing command executions
+const activeCommands = new Map();
+const startMarkerText = 'TMUX_MCP_START';
+const endMarkerPrefix = "TMUX_MCP_DONE_";
+// Track fc_shell initialization per pane to keep terminal output minimal
+const fcShellInitializedPanes = new Set();
+// Execute a command in a tmux pane and track its execution
+export async function executeCommand(paneId, command, rawMode, noEnter) {
+    // Generate unique ID for this command execution
+    const commandId = uuidv4();
+    const shellType = resolveShellType(paneId);
+    let fullCommand;
+    if (rawMode || noEnter) {
+        fullCommand = command;
+    }
+    else {
+        if (shellType === 'fc_shell') {
+            await ensureFcShellInitialized(paneId);
+            fullCommand = buildFcShellCommand(command);
+        }
+        else {
+            fullCommand = buildWrappedCommand(command, shellType);
+        }
+    }
+    // Store command in tracking map
+    activeCommands.set(commandId, {
+        id: commandId,
+        paneId,
+        command,
+        status: 'pending',
+        startTime: new Date(),
+        rawMode: rawMode || noEnter
+    });
+    // Send the command to the tmux pane
+    if (noEnter) {
+        // Check if this is a special key (e.g., Up, Down, Left, Right, Escape, Tab, etc.)
+        // Special keys in tmux are typically capitalized or have special names
+        const specialKeys = ['Up', 'Down', 'Left', 'Right', 'Escape', 'Tab', 'Enter', 'Space',
+            'BSpace', 'Delete', 'Home', 'End', 'PageUp', 'PageDown',
+            'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12'];
+        if (specialKeys.includes(fullCommand)) {
+            // Send special key as-is
+            await executeTmux(`send-keys -t '${paneId}' ${fullCommand}`);
+        }
+        else {
+            // For regular text, send each character individually to ensure proper processing
+            // This handles both single characters (like 'q', 'f') and strings (like 'beam')
+            for (const char of fullCommand) {
+                await executeTmux(`send-keys -t '${paneId}' '${char.replace(/'/g, "'\\''")}'`);
+            }
+        }
+    }
+    else {
+        await executeTmux(`send-keys -t '${paneId}' '${fullCommand.replace(/'/g, "'\\''")}' Enter`);
+    }
+    return commandId;
+}
+export async function checkCommandStatus(commandId) {
+    const command = activeCommands.get(commandId);
+    if (!command)
+        return null;
+    if (command.status !== 'pending')
+        return command;
+    const content = await capturePaneContent(command.paneId, 1000);
+    if (command.rawMode) {
+        command.result = 'Status tracking unavailable for rawMode commands. Use capture-pane to monitor interactive apps instead.';
+        return command;
+    }
+    // Find the last occurrence of the markers
+    const startIndex = content.lastIndexOf(startMarkerText);
+    const endIndex = content.lastIndexOf(endMarkerPrefix);
+    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+        command.result = "Command output could not be captured properly";
+        return command;
+    }
+    // Extract exit code from the end marker line
+    const endLine = content.substring(endIndex).split('\n')[0];
+    const endMarkerRegex = new RegExp(`${endMarkerPrefix}(\\d+)`);
+    const exitCodeMatch = endLine.match(endMarkerRegex);
+    if (exitCodeMatch) {
+        const exitCode = parseInt(exitCodeMatch[1], 10);
+        command.status = exitCode === 0 ? 'completed' : 'error';
+        command.exitCode = exitCode;
+        // Extract output between the start and end markers
+        const outputStart = startIndex + startMarkerText.length;
+        const outputContent = content.substring(outputStart, endIndex).trim();
+        const outputLines = outputContent ? outputContent.split('\n') : [];
+        if (outputLines.length > 0) {
+            const firstLine = outputLines[0].trim();
+            if (firstLine === command.command.trim()) {
+                outputLines.shift();
+            }
+        }
+        command.result = outputLines.join('\n').trim();
+        // Update in map
+        activeCommands.set(commandId, command);
+    }
+    return command;
+}
+// Get command by ID
+export function getCommand(commandId) {
+    return activeCommands.get(commandId) || null;
+}
+// Get all active command IDs
+export function getActiveCommandIds() {
+    return Array.from(activeCommands.keys());
+}
+// Clean up completed commands older than a certain time
+export function cleanupOldCommands(maxAgeMinutes = 60) {
+    const now = new Date();
+    for (const [id, command] of activeCommands.entries()) {
+        const ageMinutes = (now.getTime() - command.startTime.getTime()) / (1000 * 60);
+        if (command.status !== 'pending' && ageMinutes > maxAgeMinutes) {
+            activeCommands.delete(id);
+        }
+    }
+}
+function getEndMarkerText(shellType) {
+    if (shellType === 'fish') {
+        return `${endMarkerPrefix}$status`;
+    }
+    if (shellType === 'fc_shell') {
+        return `${endMarkerPrefix}$::tmux_mcp_status`;
+    }
+    return `${endMarkerPrefix}$?`;
+}
+function buildWrappedCommand(command, shellType) {
+    const endMarkerText = getEndMarkerText(shellType);
+    return `echo "${startMarkerText}"; ${command}; echo "${endMarkerText}"`;
+}
+function buildFcShellCommand(command) {
+    const escaped = escapeForTcl(command);
+    return `::tmux_mcp::run {${escaped}}`;
+}
+function escapeForTcl(command) {
+    return command
+        .replace(/\\/g, '\\\\')
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n')
+        .replace(/\{/g, '\\{')
+        .replace(/\}/g, '\\}');
+}
+async function ensureFcShellInitialized(paneId) {
+    if (fcShellInitializedPanes.has(paneId)) {
+        return;
+    }
+    const definitionCommand = [
+        'namespace eval ::tmux_mcp {',
+        'proc run {cmd} {',
+        `puts "${startMarkerText}";`,
+        'set status [catch {uplevel #0 $cmd} result opts];',
+        'if {$status == 0} {',
+        'if {[info exists result] && $result ne ""} { puts $result }',
+        '} else {',
+        'if {[info exists opts(-errorinfo)]} { puts $opts(-errorinfo) } else { puts $result }',
+        '};',
+        `puts "${endMarkerPrefix}$status"`,
+        '}',
+        '}'
+    ].join(' ');
+    const escapedCommand = definitionCommand.replace(/'/g, "'\\''");
+    await executeTmux(`send-keys -t '${paneId}' '${escapedCommand}' Enter`);
+    fcShellInitializedPanes.add(paneId);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@arearseth/tmux-mcp",
+  "version": "0.2.2",
+  "description": "MCP Server for interfacing with tmux sessions",
+  "type": "module",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsc -w",
+    "test": "vitest run",
+    "check-release": "npm run build && npm publish --dry-run",
+    "release": "npm run build && npm publish"
+  },
+  "bin": {
+    "tmux-mcp": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "mcp",
+    "tmux",
+    "claude"
+  ],
+  "author": "nickgnd",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.2",
+    "uuid": "^11.1.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "@types/uuid": "^10.0.0",
+    "vitest": "^1.6.0",
+    "typescript": "^5.3.3"
+  },
+  "repository": "github:AreAArseth/tmux-mcp",
+  "bugs": {
+    "url": "https://github.com/AreAArseth/tmux-mcp/issues"
+  },
+  "homepage": "https://github.com/AreAArseth/tmux-mcp#readme"
+}