new_session

Instructions

Implementation Reference

• server.js:154-195 (handler)

  The handler function for the 'new_session' tool. It validates the session name, checks for existing session, creates a new detached tmux session (optionally with a cwd), and optionally sends a command via send-keys. Returns session info or an error.

  async function newSession(args) {
    const missing = requireTmux();
    if (missing) return errorResult(missing);
    const bad = validSessionName(args.name);
    if (bad) return errorResult(bad);
  
    // Check for an existing session first — tmux would error with "duplicate
    // session" but the error text varies across versions; our own check is
    // clearer for the caller.
    const existing = await run(BIN.tmux, ['has-session', '-t', `=${args.name}`]);
    if (existing.code === 0) {
      return errorResult(`session "${args.name}" already exists. Use kill_session first or pick a different name.`);
    }
  
    // Always start a shell (no explicit command arg) so the session survives
    // after the initial command finishes. If `command` is provided, send it as
    // keystrokes so it runs inside the shell — respecting aliases, venvs,
    // functions, etc.
    const createArgs = ['new-session', '-d', '-s', args.name];
    if (args.cwd && typeof args.cwd === 'string') {
      createArgs.push('-c', args.cwd);
    }
    const created = await run(BIN.tmux, createArgs);
    if (created.code !== 0) {
      return errorResult(`tmux new-session failed: ${created.stderr || created.stdout}`);
    }
  
    if (args.command && typeof args.command === 'string' && args.command.trim()) {
      const r = await run(BIN.tmux, ['send-keys', '-t', `=${args.name}:`, args.command, 'Enter']);
      if (r.code !== 0) {
        return errorResult(`session created, but send-keys failed: ${r.stderr || r.stdout}`);
      }
    }
  
    return textResult({
      name: args.name,
      cwd: args.cwd || null,
      command: args.command || null,
      status: 'running',
      hint: `Use capture_pane name="${args.name}" to check output; tmux attach -t "${args.name}" from a real terminal to watch live.`,
    });
  }

• server.js:281-295 (schema)

  The tool schema/registration entry for 'new_session' in the TOOLS array. Defines name, description, annotations, and inputSchema (properties: name, command, cwd; required: name).

  {
    name: 'new_session',
    description: 'Start a new detached tmux session. Always starts a shell (so the session survives after the initial command finishes). If `command` is given, it is sent to the shell as keystrokes + Enter, so aliases, venvs, and functions work as expected. Errors if the session name already exists.',
    annotations: { title: 'Start tmux session', readOnlyHint: false, destructiveHint: true, openWorldHint: true },
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Session name (unique). Cannot contain ".", ":", "|", or whitespace.' },
        command: { type: 'string', description: 'Optional initial command to run inside the shell (e.g. "cd /path && python train.py").' },
        cwd: { type: 'string', description: 'Optional starting working directory for the session.' },
      },
      required: ['name'],
      additionalProperties: false,
    },
  },

• server.js:326-334 (registration)

  The HANDLERS map that registers the 'new_session' tool name to the newSession handler function, used for dispatch in tools/call.

  const HANDLERS = {
    list_sessions: listSessions,
    has_session: hasSession,
    list_windows: listWindows,
    capture_pane: capturePane,
    new_session: newSession,
    send_keys: sendKeys,
    kill_session: killSession,
  };

• server.js:69-74 (helper)

  The validSessionName helper function used by new_session to validate the session name (no '.', ':', '|', or whitespace, max 100 chars).

  function validSessionName(name) {
    if (typeof name !== 'string' || !name.length) return 'name is required (non-empty string)';
    if (name.length > 100) return 'name too long (max 100)';
    if (/[.:\s|]/.test(name)) return "name cannot contain '.', ':', '|', or whitespace";
    return null;
  }