tmux_select_window

Switch to a specific window in a tmux session by specifying the session name and window identifier to manage terminal workflows.

Instructions

Switch to a specific window in a tmux session.

Args:

session (string, required): Name of the session
window (string or number, required): Window index or name

Input Schema

TableJSON Schema

Name	Required	Description	Default
`session`	Yes	Name of the session
`window`	Yes	Window index or name

Implementation Reference

src/index.ts:720-735 (handler)

The handler function for the tmux_select_window tool. It formats the target using formatTarget, runs the tmux select-window command via runTmux, and returns success or error response.

async ({ session, window }) => {
  try {
    const target = formatTarget(session, window);
    await runTmux(`select-window -t "${target}"`);

    return {
      content: [{ type: "text", text: `Switched to window '${window}' in session '${session}'.` }],
      structuredContent: { success: true, session, window },
    };
  } catch (error) {
    return {
      content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
      isError: true,
    };
  }
}

src/index.ts:707-712 (schema)

Zod input schema defining required parameters: session (string) and window (string or number).

inputSchema: z
  .object({
    session: z.string().min(1).describe("Name of the session"),
    window: z.union([z.string(), z.number()]).describe("Window index or name"),
  })
  .strict(),

src/index.ts:698-736 (registration)

Registers the tmux_select_window tool with the MCP server using server.registerTool, providing name, metadata (title, description, schema, annotations), and handler function.

server.registerTool(
  "tmux_select_window",
  {
    title: "Select tmux Window",
    description: `Switch to a specific window in a tmux session.

Args:
  - session (string, required): Name of the session
  - window (string or number, required): Window index or name`,
    inputSchema: z
      .object({
        session: z.string().min(1).describe("Name of the session"),
        window: z.union([z.string(), z.number()]).describe("Window index or name"),
      })
      .strict(),
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  },
  async ({ session, window }) => {
    try {
      const target = formatTarget(session, window);
      await runTmux(`select-window -t "${target}"`);

      return {
        content: [{ type: "text", text: `Switched to window '${window}' in session '${session}'.` }],
        structuredContent: { success: true, session, window },
      };
    } 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 asynchronously with execAsync and custom error messages for common tmux issues.

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

src/index.ts:70-82 (helper)

Shared utility function to construct tmux target strings in the format 'session:window.pane' from parameters.

function formatTarget(session?: string, window?: number | string, pane?: number): string {
  let target = "";
  if (session) {
    target = session;
    if (window !== undefined) {
      target += `:${window}`;
      if (pane !== undefined) {
        target += `.${pane}`;
      }
    }
  }
  return target;
}

Tmux MCP Server