List tmux Sessions

Instructions

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