get_tabs

Instructions

Implementation Reference

• src/index.ts:286-327 (handler)

  Handler for executing the 'get_tabs' tool: fetches Chrome tabs using getChromeTabsWithIds(), formats them with unique Tab IDs and safety instructions, returns formatted text response.

        if (name === "get_tabs") {
          const windows = await getChromeTabsWithIds();
          
          const formattedOutput = windows
            .map((window) => {
              const activeTab = window.tabs.find(tab => tab.isActive);
              const activeIndicator = activeTab ? ` (Active: Tab ID ${activeTab.id})` : "";
              
              return `Window ${window.windowIndex}${activeIndicator}:
  ${window.tabs
    .map((tab) => {
      const activeMarker = tab.isActive ? " ★" : "";
      return `  ${window.windowIndex}-${tab.tabIndex}. ${tab.title}${activeMarker}
       ${tab.url}
       [Tab ID: ${tab.id}]${activeMarker}`;
    })
    .join("\n")}`;
            })
            .join("\n\n");
  
          const totalTabs = windows.reduce((sum, window) => sum + window.tabs.length, 0);
          
          return {
            content: [
              {
                type: "text",
                text: `Found ${totalTabs} open tabs in Chrome:
  
  ${formattedOutput}
  
  🔥 CRITICAL INSTRUCTIONS FOR AI:
  1. ALWAYS use Tab ID (numbers in [Tab ID: xxxxx]) for tab operations
  2. NEVER use display numbers (1-1, 1-2) - these are just for human reference
  3. Use close_tab_by_id or activate_tab_by_id with the Tab ID number
  4. Example: If you see "[Tab ID: 1594670961]", use tabId: 1594670961
  
  ⚠️ DANGER: Window-Tab index changes when tabs are reordered/closed
  ✅ SAFE: Tab ID never changes and is unique across all tabs`,
              },
            ],
          };
        }

• src/index.ts:235-239 (registration)

  Registration of the 'get_tabs' tool in the listTools response, including name, description, and empty input schema (no parameters required).

  {
    name: "get_tabs",
    description: "Get all open tabs from Google Chrome browser with unique tab IDs. Each tab has a stable, unique ID that persists across browser operations. Output shows both display format (1-1, 1-2) and Tab ID [Tab ID: 1234567890] for each tab. ALWAYS use the Tab ID number for reliable operations.",
    inputSchema: zodToJsonSchema(z.object({})),
  },

• src/index.ts:238-239 (schema)

  Input schema for get_tabs tool: empty object since no input parameters are needed.

    inputSchema: zodToJsonSchema(z.object({})),
  },

• src/index.ts:34-104 (helper)

  Core helper function that runs AppleScript to fetch all Chrome tabs with unique IDs, parses the pipe-delimited output, groups by window, and returns structured ChromeWindow[] data used by the get_tabs handler.

  async function getChromeTabsWithIds(): Promise<ChromeWindow[]> {
    const script = `
      tell application "Google Chrome"
        set windowList to windows
        set output to ""
        repeat with windowIndex from 1 to count of windowList
          set theWindow to item windowIndex of windowList
          set windowID to id of theWindow
          set activeTabIndex to active tab index of theWindow
          set tabList to tabs of theWindow
          repeat with tabIndexInWindow from 1 to count of tabList
            set theTab to item tabIndexInWindow of tabList
            set tabID to id of theTab
            set isActive to (tabIndexInWindow = activeTabIndex)
            set output to output & windowID & "|||" & windowIndex & "|||" & tabID & "|||" & tabIndexInWindow & "|||" & isActive & "|||" & (title of theTab) & "|||" & (URL of theTab) & "\\n"
          end repeat
        end repeat
        return output
      end tell
    `;
  
    try {
      const { stdout } = await execAsync(`osascript -e '${script}'`);
      const tabsData = stdout
        .trim()
        .split("\n")
        .filter((line) => line.length > 0)
        .map((line) => {
          const [windowId, windowIndex, tabId, tabIndex, isActive, title, url] = line.split("|||");
          return {
            windowId: Number.parseInt(windowId, 10),
            windowIndex: Number.parseInt(windowIndex, 10),
            tabId: Number.parseInt(tabId, 10),
            tabIndex: Number.parseInt(tabIndex, 10),
            isActive: isActive === "true",
            title: title || "",
            url: url || "",
          };
        });
  
      // Group by windows
      const windowMap = new Map<number, ChromeWindow>();
      
      for (const tabData of tabsData) {
        if (!windowMap.has(tabData.windowId)) {
          windowMap.set(tabData.windowId, {
            windowId: tabData.windowId,
            windowIndex: tabData.windowIndex,
            tabs: [],
          });
        }
        
        const window = windowMap.get(tabData.windowId)!;
        window.tabs.push({
          id: tabData.tabId,
          windowId: tabData.windowId,
          title: tabData.title,
          url: tabData.url,
          isActive: tabData.isActive,
          windowIndex: tabData.windowIndex,
          tabIndex: tabData.tabIndex,
        });
      }
  
      return Array.from(windowMap.values());
    } catch (error) {
      throw new Error(
        `Failed to get Chrome tabs: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/index.ts:17-25 (helper)

  Type interfaces for ChromeTab and ChromeWindow used throughout the get_tabs implementation.

  interface ChromeTab {
    id: number;           // Unique Chrome tab ID
    windowId: number;     // Window ID
    title: string;
    url: string;
    isActive: boolean;
    windowIndex: number;  // For backward compatibility
    tabIndex: number;     // For backward compatibility
  }