tmux_create_window

Create a new window in a tmux session with optional naming and starting directory configuration for organized terminal workspace management.

Instructions

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

Input Schema

TableJSON Schema

Name	Required	Description
`session`	Yes	Name of the session
`name`	No	Name for the new window
`start_directory`	No	Starting directory for the window

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

Tmux MCP Server