Tmux MCP Server

Instructions

Implementation Reference

• src/tmux.ts:200-234 (handler)

  Core handler function that implements the split-pane logic by constructing tmux 'split-window' command with direction and size options, executing it, and returning the new pane details.

  export async function splitPane(
    targetPaneId: string,
    direction: 'horizontal' | 'vertical' = 'vertical',
    size?: number
  ): Promise<TmuxPane | null> {
    // 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;
  }

• src/index.ts:315-344 (registration)

  MCP tool registration for 'split-pane', defining input schema with Zod and wrapper handler that delegates to tmux.splitPane and formats response.

  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
        };
      }
    }
  );

• src/index.ts:319-322 (schema)

  Zod input schema for the split-pane tool parameters: paneId (required string), direction (optional enum), size (optional number 1-99).

    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%")
  },