list_surfaces
Lists all terminal and browser panes across workspaces to manage parallel AI agent sessions and monitor their activities.
Instructions
List all surfaces (terminal/browser panes) across workspaces
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | Filter by workspace ref | |
| include_screen_preview | No | Include screen content preview | |
| preview_lines | No | Number of preview lines |
Implementation Reference
- src/server.ts:141-219 (handler)The 'list_surfaces' tool is defined and registered in src/server.ts, providing a handler that interacts with the CmuxClient to list workspaces, panes, and surfaces, with optional screen preview capabilities.
// 1. list_surfaces server.tool( "list_surfaces", "List all surfaces (terminal/browser panes) across workspaces", { workspace: z.string().optional().describe("Filter by workspace ref"), include_screen_preview: z .boolean() .optional() .default(false) .describe("Include screen content preview"), preview_lines: z .number() .int() .min(1) .max(50) .optional() .default(8) .describe("Number of preview lines"), }, async (args) => { try { const workspaces = await client.listWorkspaces(); const targetWorkspaceRefs = args.workspace ? [args.workspace] : workspaces.workspaces.map((workspace) => workspace.ref); const panesByWorkspace = await Promise.all( targetWorkspaceRefs.map(async (workspaceRef) => ({ workspaceRef, panes: await client.listPanes({ workspace: workspaceRef }), })), ); const surfaceGroups = await Promise.all( panesByWorkspace.flatMap(({ workspaceRef, panes }) => panes.panes.map((pane) => client.listPaneSurfaces({ workspace: workspaceRef, pane: pane.ref, }), ), ), ); const surfaces = await Promise.all( surfaceGroups.flatMap((group) => group.surfaces.map(async (surface) => { const enrichedSurface: Record<string, unknown> = { ...surface, workspace_ref: group.workspace_ref, window_ref: group.window_ref, pane_ref: group.pane_ref, }; if (args.include_screen_preview && surface.type === "terminal") { try { const preview = await client.readScreen(surface.ref, { workspace: group.workspace_ref, lines: args.preview_lines, }); enrichedSurface.screen_preview = preview.text; } catch (error) { enrichedSurface.screen_preview_error = error instanceof Error ? error.message : String(error); } } return enrichedSurface; }), ), ); return ok({ workspaces: workspaces.workspaces, surfaces, workspace_ref: args.workspace, }); } catch (e) { return err(e); } }, );