Create tmux Window

Instructions

Implementation Reference

• src/index.ts:338-359 (handler)

  Handler function that executes the tmux_create_window tool logic by constructing and running the 'tmux new-window' command with optional name and start_directory.

  async ({ session, name, start_directory }) => {
    try {
      let cmd = `new-window -t "${session}"`;
      if (name) {
        cmd += ` -n "${name}"`;
      }
      if (start_directory) {
        cmd += ` -c "${start_directory}"`;
      }
      await runTmux(cmd);
  
      return {
        content: [{ type: "text", text: `Window${name ? ` '${name}'` : ""} created in session '${session}'.` }],
        structuredContent: { success: true, session, window: name },
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
        isError: true,
      };
    }
  }

• src/index.ts:324-331 (schema)

  Zod input schema defining parameters for the tmux_create_window tool: session (required), name (optional), start_directory (optional).

  inputSchema: z
    .object({
      session: z.string().min(1).describe("Name of the session"),
      name: z.string().optional().describe("Name for the new window"),
      start_directory: z.string().optional().describe("Starting directory for the window"),
    })
    .strict(),
  annotations: {

• src/index.ts:314-360 (registration)

  Registration of the tmux_create_window tool with McpServer, including title, description, schema, annotations, and inline handler.

  server.registerTool(
    "tmux_create_window",
    {
      title: "Create tmux Window",
      description: `Create a new window in a tmux session.
  
  Args:
    - session (string, required): Name of the session
    - name (string, optional): Name for the new window
    - start_directory (string, optional): Starting directory for the window`,
      inputSchema: z
        .object({
          session: z.string().min(1).describe("Name of the session"),
          name: z.string().optional().describe("Name for the new window"),
          start_directory: z.string().optional().describe("Starting directory for the window"),
        })
        .strict(),
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },
    },
    async ({ session, name, start_directory }) => {
      try {
        let cmd = `new-window -t "${session}"`;
        if (name) {
          cmd += ` -n "${name}"`;
        }
        if (start_directory) {
          cmd += ` -c "${start_directory}"`;
        }
        await runTmux(cmd);
  
        return {
          content: [{ type: "text", text: `Window${name ? ` '${name}'` : ""} created in session '${session}'.` }],
          structuredContent: { success: true, session, window: name },
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
          isError: true,
        };
      }
    }
  );

• src/index.ts:45-68 (helper)

  Shared utility function to execute tmux commands via child_process.exec, with custom error messages for common tmux errors.

  async function runTmux(args: string): Promise<string> {
    try {
      const { stdout } = await execAsync(`tmux ${args}`);
      return stdout.trim();
    } catch (error: unknown) {
      if (error instanceof Error && "stderr" in error) {
        const stderr = (error as { stderr: string }).stderr;
        if (stderr.includes("no server running")) {
          throw new Error("tmux server is not running. Start a session first with tmux_create_session.");
        }
        if (stderr.includes("session not found")) {
          throw new Error("Session not found. Use tmux_list_sessions to see available sessions.");
        }
        if (stderr.includes("window not found")) {
          throw new Error("Window not found. Use tmux_list_windows to see available windows.");
        }
        if (stderr.includes("can't find pane")) {
          throw new Error("Pane not found. Use tmux_list_panes to see available panes.");
        }
        throw new Error(`tmux error: ${stderr}`);
      }
      throw error;
    }
  }