tmux_create_session
Create a new tmux session with a custom name, window label, and starting directory to organize terminal workflows in detached mode.
Instructions
Create a new tmux session.
Args:
name (string, required): Name for the new session
window_name (string, optional): Name for the initial window
start_directory (string, optional): Starting directory for the session
The session is created in detached mode. Use this to start new working environments.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new session | |
| window_name | No | Name for the initial window | |
| start_directory | No | Starting directory for the session |
Implementation Reference
- src/index.ts:189-210 (handler)Handler function that executes tmux new-session command with optional window name and start directory.async ({ name, window_name, start_directory }) => { try { let cmd = `new-session -d -s "${name}"`; if (window_name) { cmd += ` -n "${window_name}"`; } if (start_directory) { cmd += ` -c "${start_directory}"`; } await runTmux(cmd); return { content: [{ type: "text", text: `Session '${name}' created successfully.` }], structuredContent: { success: true, session: name }, }; } catch (error) { return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, }; } }
- src/index.ts:175-181 (schema)Zod schema for input validation: name (required string), window_name and start_directory (optional strings).inputSchema: z .object({ name: z.string().min(1).describe("Name for the new session"), window_name: z.string().optional().describe("Name for the initial window"), start_directory: z.string().optional().describe("Starting directory for the session"), }) .strict(),
- src/index.ts:163-211 (registration)Registration of the tmux_create_session tool using server.registerTool, including title, description, schema, annotations, and handler.server.registerTool( "tmux_create_session", { title: "Create tmux Session", description: `Create a new tmux session. Args: - name (string, required): Name for the new session - window_name (string, optional): Name for the initial window - start_directory (string, optional): Starting directory for the session The session is created in detached mode. Use this to start new working environments.`, inputSchema: z .object({ name: z.string().min(1).describe("Name for the new session"), window_name: z.string().optional().describe("Name for the initial window"), start_directory: z.string().optional().describe("Starting directory for the session"), }) .strict(), annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false, }, }, async ({ name, window_name, start_directory }) => { try { let cmd = `new-session -d -s "${name}"`; if (window_name) { cmd += ` -n "${window_name}"`; } if (start_directory) { cmd += ` -c "${start_directory}"`; } await runTmux(cmd); return { content: [{ type: "text", text: `Session '${name}' created successfully.` }], structuredContent: { success: true, session: name }, }; } catch (error) { return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, }; } } );
- src/index.ts:45-68 (helper)Utility function runTmux that executes tmux commands and handles common errors, used by the handler.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; } }