tmux_list_windows
List all windows in a tmux session to view their index, name, active status, and pane count for session management.
Instructions
List all windows in a tmux session.
Args:
session (string, required): Name of the session
Returns information about each window including index, name, active status, and pane count.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| session | Yes | Name of the session |
Implementation Reference
- src/index.ts:277-311 (handler)Main handler function that lists windows in the specified tmux session by executing 'tmux list-windows' with a custom format, parsing the output into TmuxWindow objects (index, name, active status, pane count), handling empty results and errors, and returning both text and structured JSON content.async ({ session }) => { try { const output = await runTmux( `list-windows -t "${session}" -F "#{window_index}|#{window_name}|#{window_active}|#{window_panes}"` ); if (!output) { return { content: [{ type: "text", text: `No windows found in session '${session}'.` }], }; } const windows: TmuxWindow[] = output.split("\n").map((line) => { const [index, name, active, panes] = line.split("|"); return { index: parseInt(index, 10), name, active: active === "1", panes: parseInt(panes, 10), }; }); const result = { session, count: windows.length, windows }; return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result, }; } catch (error) { return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, }; } }
- src/index.ts:265-269 (schema)Zod input schema defining the required 'session' parameter as a non-empty string.inputSchema: z .object({ session: z.string().min(1).describe("Name of the session"), }) .strict(),
- src/index.ts:29-33 (schema)TypeScript interface defining the structure of a tmux window object used in the tool's output.index: number; name: string; active: boolean; panes: number; }
- src/index.ts:255-312 (registration)Full registration of the tmux_list_windows tool with McpServer, including name, tool specification (title, description, input schema, annotations), and inline handler function.server.registerTool( "tmux_list_windows", { title: "List tmux Windows", description: `List all windows in a tmux session. Args: - session (string, required): Name of the session Returns information about each window including index, name, active status, and pane count.`, inputSchema: z .object({ session: z.string().min(1).describe("Name of the session"), }) .strict(), annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, }, async ({ session }) => { try { const output = await runTmux( `list-windows -t "${session}" -F "#{window_index}|#{window_name}|#{window_active}|#{window_panes}"` ); if (!output) { return { content: [{ type: "text", text: `No windows found in session '${session}'.` }], }; } const windows: TmuxWindow[] = output.split("\n").map((line) => { const [index, name, active, panes] = line.split("|"); return { index: parseInt(index, 10), name, active: active === "1", panes: parseInt(panes, 10), }; }); const result = { session, count: windows.length, windows }; return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result, }; } catch (error) { return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, }; } } );
- src/index.ts:45-68 (helper)Utility function to execute tmux commands asynchronously, handling common errors like no server, session/window/pane not found with helpful messages referencing this tool.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; } }