tmux_list_sessions
List active tmux sessions with details like name, window count, creation time, and attachment status to manage terminal sessions.
Instructions
List all active tmux sessions.
Returns information about each session including:
Session name
Number of windows
Creation time
Whether the session is currently attached
Use this tool to discover available sessions before operating on them.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/index.ts:125-161 (handler)The handler function that lists all tmux sessions by executing 'tmux list-sessions' with a custom format, parsing the output into a structured array of sessions (name, windows, created time, attached status), and returning JSON-formatted text content with structured data.async () => { try { const output = await runTmux('list-sessions -F "#{session_name}|#{session_windows}|#{session_created}|#{session_attached}"'); if (!output) { return { content: [{ type: "text", text: "No tmux sessions found." }], }; } const sessions: TmuxSession[] = output.split("\n").map((line) => { const [name, windows, created, attached] = line.split("|"); return { name, windows: parseInt(windows, 10), created: new Date(parseInt(created, 10) * 1000).toISOString(), attached: attached === "1", }; }); const result = { count: sessions.length, sessions, }; 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:106-124 (schema)The tool schema defining title, multi-line description, empty input schema (no parameters required), and annotations indicating it is read-only, non-destructive, idempotent, and not open-world.{ title: "List tmux Sessions", description: `List all active tmux sessions. Returns information about each session including: - Session name - Number of windows - Creation time - Whether the session is currently attached Use this tool to discover available sessions before operating on them.`, inputSchema: z.object({}).strict(), annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, },
- src/index.ts:104-161 (registration)The server.registerTool call that registers the 'tmux_list_sessions' tool with its schema and inline handler function.server.registerTool( "tmux_list_sessions", { title: "List tmux Sessions", description: `List all active tmux sessions. Returns information about each session including: - Session name - Number of windows - Creation time - Whether the session is currently attached Use this tool to discover available sessions before operating on them.`, inputSchema: z.object({}).strict(), annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, }, async () => { try { const output = await runTmux('list-sessions -F "#{session_name}|#{session_windows}|#{session_created}|#{session_attached}"'); if (!output) { return { content: [{ type: "text", text: "No tmux sessions found." }], }; } const sessions: TmuxSession[] = output.split("\n").map((line) => { const [name, windows, created, attached] = line.split("|"); return { name, windows: parseInt(windows, 10), created: new Date(parseInt(created, 10) * 1000).toISOString(), attached: attached === "1", }; }); const result = { count: sessions.length, sessions, }; 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 via child_process.exec, handles common tmux errors like no server or session not found, and returns trimmed stdout.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:21-26 (schema)TypeScript interface defining the structure of a tmux session object used in the tool's output.interface TmuxSession { name: string; windows: number; created: string; attached: boolean; }