2manytabs-mcp-host 2.1.0 → 3.1.0

package/tools/execute-script.tool.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+const MAX_OUTPUT_CHARS = 50_000;
+
+export const executeScriptTool = {
+  name: 'execute_script',
+  title: 'Execute Script in Tab',
+  description:
+    'Execute a JavaScript expression or script in the context of an open browser tab and return the serialized result. ' +
+    'Useful for pulling elements from pages (e.g. images, links, tables, article bodies), clicking elements, or extracting dynamic DOM state. ' +
+    'Firefox only: Chrome tabs return an error, so use a firefox: tab id. ' +
+    'Fails on restricted system URLs (e.g. chrome://, about:, extensions).',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    tab_id: z.union([z.number().int(), z.string()])
+      .describe('The target tab ID (number or composite ID like "chrome:12" or "firefox:34").'),
+    script: z.string()
+      .describe('The JavaScript code or expression to run in the tab. Can return a value or a Promise (e.g. Array.from(document.images).map(i => i.src)).'),
+    browser: z.string().optional()
+      .describe('Optional browser hint ("chrome", "firefox") if tab_id is numeric and ambiguous.'),
+    world: z.enum(['ISOLATED', 'MAIN']).default('ISOLATED')
+      .describe('Execution context world. "ISOLATED" (default) has full DOM access. "MAIN" runs in the page JavaScript window context.'),
+  },
+
+  execute: async ({ tab_id, script, browser, world }) => {
+    const res = await callExtension('execute_script', { tab_id, script, browser, world });
+    if (!res || res.success === false) {
+      throw new Error(res?.error || 'Script execution failed without error details.');
+    }
+
+    const value = res.result;
+    let output;
+    if (typeof value === 'string') {
+      output = value;
+    } else if (value === null || value === undefined) {
+      output = '(null / undefined returned)';
+    } else {
+      output = JSON.stringify(value, null, 2);
+    }
+
+    if (output.length > MAX_OUTPUT_CHARS) {
+      output = output.slice(0, MAX_OUTPUT_CHARS) +
+        `\n\n... [Result truncated: exceeded ${MAX_OUTPUT_CHARS} characters]`;
+    }
+
+    return output;
+  },
+};

package/tools/get-tab-text.tool.js

@@ -15,12 +15,14 @@ export const getTabTextTool = {
     openWorldHint: true,
   },
   inputSchema: {
-    tab_id: z.number().int()
-      .describe('The numeric ID of the tab whose body text to extract.'),
+    tab_id: z.union([z.number().int(), z.string()])
+      .describe('The numeric ID (or composite like "chrome:123") of the tab whose body text to extract.'),
+    browser: z.string().optional()
+      .describe('Optional browser hint ("chrome", "firefox") if tab_id is numeric.'),
   },
 
-  execute: async ({ tab_id }) => {
-    const res = await callExtension('get_tab_text', { tab_id });
+  execute: async ({ tab_id, browser }) => {
+    const res = await callExtension('get_tab_text', { tab_id, browser });
     if (!res.text) {
       return `Tab ${tab_id} returned no text content (it might be empty, loading, or restricted).`;
     }

package/tools/group-tabs.tool.js

@@ -1,12 +1,17 @@
 import { z } from 'zod';
 import { callExtension } from '../bridge.js';
+import { GROUP_TITLE_DESCRIBE, groupTitleNote } from '../lib/tabs.js';
 
 export const groupTabsTool = {
   name: 'group_tabs',
   title: 'Group Tabs',
   description:
-    'Group open Chrome tabs into native Chrome Tab Groups. Can create a new group or ' +
-    'add tabs to an existing group. Optionally set a title and a color for the group.',
+    'Group open tabs into native browser tab groups. Can create a new group or ' +
+    'add tabs to an existing group. Optionally set a title and a color for the group. ' +
+    'Tabs stay in their own windows: a group cannot span windows, so tabs from several ' +
+    'windows become one matching group per window. Grouping does move tabs next to each ' +
+    'other in the tab bar while the user may be using it, so say that before you group. ' +
+    'The user is left on the tab they were on.',
   annotations: {
     readOnlyHint: false,
     destructiveHint: false,
@@ -14,21 +19,29 @@ export const groupTabsTool = {
     openWorldHint: true,
   },
   inputSchema: {
-    tab_ids: z.array(z.number().int()).min(1)
-      .describe('Array of tab IDs to add to the group.'),
-    group_id: z.number().int().optional()
-      .describe('Add to an existing group ID. If omitted, a new group is created.'),
+    tab_ids: z.array(z.union([z.number().int(), z.string()])).min(1)
+      .describe('Tab IDs to add to the group (numbers or composite like "chrome:12"). All must be in the same browser.'),
+    group_id: z.union([z.number().int(), z.string()]).optional()
+      .describe('Add to an existing group ID (number or composite like "chrome:5"). If omitted, a new group is created.'),
     title: z.string().optional()
-      .describe('Title to set on the group (new or existing).'),
+      .describe(GROUP_TITLE_DESCRIBE),
     color: z.enum(['grey', 'blue', 'red', 'yellow', 'green', 'pink', 'purple', 'cyan', 'orange']).optional()
       .describe('Color to set on the group (new or existing).'),
+    browser: z.string().optional()
+      .describe('Optional browser hint ("chrome", "firefox") if ids are numeric.'),
   },
 
-  execute: async ({ tab_ids, group_id, title, color }) => {
-    const res = await callExtension('group_tabs', { tab_ids, group_id, title, color });
+  execute: async ({ tab_ids, group_id, title, color, browser }) => {
+    const res = await callExtension('group_tabs', { tab_ids, group_id, title, color, browser });
+    const grouped = res.grouped ?? tab_ids.length;
+    const windows = res.windows ?? 1;
     return JSON.stringify({
-      message: `Successfully grouped ${tab_ids.length} tab(s).`,
+      message: windows > 1
+        ? `Grouped ${grouped} tab(s) as ${windows} matching groups, one per window. No tab changed window.`
+        : `Grouped ${grouped} tab(s).`,
       groupId: res.groupId,
+      groupIds: res.groupIds ?? [res.groupId],
+      title_note: groupTitleNote(title),
     }, null, 2);
   },
 };

package/tools/index.js

@@ -1,7 +1,3 @@
-// Tool registry — the single place that knows which tools exist.
-// To add a tool: create ./my-thing.tool.js exporting a tool object, then add it here.
-// host.js handles all SDK wiring (schema generation, validation, dispatch) generically.
-
 import { listTabsTool }  from './list-tabs.tool.js';
 import { closeTabsTool } from './close-tabs.tool.js';
 import { openTabsTool }  from './open-tabs.tool.js';
@@ -12,10 +8,19 @@ import { updateTabGroupTool } from './update-tab-group.tool.js';
 import { activateTabTool } from './activate-tab.tool.js';
 import { updateTabTool } from './update-tab.tool.js';
 import { getTabTextTool } from './get-tab-text.tool.js';
+import { executeScriptTool } from './execute-script.tool.js';
+import { startTabCleanupTool } from './start-tab-cleanup.tool.js';
+import { snapshotTabsTool } from './snapshot-tabs.tool.js';
+import { clusterTabsTool } from './cluster-tabs.tool.js';
+import { reopenTabsTool } from './reopen-tabs.tool.js';
 
 export const toolRegistry = [
+  startTabCleanupTool,
   listTabsTool,
+  clusterTabsTool,
+  snapshotTabsTool,
   closeTabsTool,
+  reopenTabsTool,
   openTabsTool,
   listTabGroupsTool,
   groupTabsTool,
@@ -24,4 +29,5 @@ export const toolRegistry = [
   activateTabTool,
   updateTabTool,
   getTabTextTool,
+  executeScriptTool,
 ];

package/tools/list-tab-groups.tool.js

@@ -5,7 +5,7 @@ export const listTabGroupsTool = {
   name: 'list_tab_groups',
   title: 'List Tab Groups',
   description:
-    'List all existing native Chrome Tab Groups in the current browser session. ' +
+    'List all existing native tab groups across all connected browsers. ' +
     'Returns their IDs, titles, colors, collapsed states, and parent window IDs.',
   annotations: { readOnlyHint: true, openWorldHint: true },
   inputSchema: {
@@ -13,7 +13,6 @@ export const listTabGroupsTool = {
       .describe('Case-insensitive substring filter for group titles.'),
   },
 
-  // fallow-ignore-next-line complexity
   execute: async ({ title_query }) => {
     let groups;
     try {
@@ -38,7 +37,7 @@ export const listTabGroupsTool = {
     for (const g of filtered) {
       const titleStr = g.title ? `"${g.title}"` : '(unnamed)';
       const collapsedStr = g.collapsed ? ' ⏸ (collapsed)' : ' ▶ (expanded)';
-      lines.push(`  · [ID: ${g.id}] ${titleStr} [Color: ${g.color}] [Window: ${g.windowId}]${collapsedStr}`);
+      lines.push(`  · [ID: ${g.browser ? `${g.browser}:${g.id}` : g.id}] ${titleStr} [Color: ${g.color}] [Window: ${g.windowId}]${collapsedStr}`);
     }
 
     return lines.join('\n');

package/tools/list-tabs.tool.js

@@ -10,10 +10,13 @@ export const listTabsTool = {
   name: 'list_tabs',
   title: 'List Tabs',
   description:
-    'Read open Chrome tabs. Returns a domain histogram (the fastest way to understand a large ' +
-    'tab set) plus a detailed view. When summarizing the results for the user, you should ' +
-    'include the histogram bar graph in your response. Filter with `query`, reshape with ' +
-    '`group_by`, or isolate redundant tabs with `duplicates_only`. Read-only — never closes anything.',
+    'Read open browser tabs: a domain histogram plus one line per tab. Best for finding ' +
+    'specific tabs with `query`. To survey, sort or clean up many tabs, use cluster_tabs ' +
+    'instead: it summarises any number of tabs in a few lines, where this prints every tab. ' +
+    'Filter with `query`, reshape with ' +
+    '`group_by`, or isolate redundant tabs with `duplicates_only`. Shows at most ' +
+    `${MAX_TAB_LIST} tabs and says so when there are more; cluster_tabs summarises any number. ` +
+    'Read-only — never closes anything.',
   annotations: { readOnlyHint: true, openWorldHint: true },
   inputSchema: {
     query: z.string().optional()
@@ -23,20 +26,26 @@ export const listTabsTool = {
         "'window' groups by browser window; 'none' returns a flat list."),
     duplicates_only: z.boolean().default(false)
       .describe('Only include tabs that are duplicates (share a URL with an earlier tab).'),
+    browser: z.string().optional()
+      .describe('Filter tabs to a specific browser (e.g. "chrome", "firefox"). Omit to list tabs across all open browsers.'),
+    show_urls: z.boolean().default(false)
+      .describe('Print each tab\'s URL under its title. Long output for many tabs: narrow with `query` first.'),
   },
 
-  execute: async ({ query, group_by, duplicates_only }) => {
-    const all = await callExtension('query_tabs');
+  execute: async ({ query, group_by, duplicates_only, browser, show_urls }) => {
+    let all = await callExtension('query_tabs');
+    if (browser) {
+      all = all.filter((t) => (t.browser || '').toLowerCase() === browser.toLowerCase());
+    }
 
-    let groups;
+    let groups = [];
     try {
       groups = await callExtension('query_groups');
-    } catch (err) {
-      console.error('Failed to fetch tab groups:', err);
-      throw new Error('Failed to fetch tab groups from extension.');
+    } catch {
+      groups = [];
     }
 
-    const groupMap = new Map(groups.map(g => [g.id, g]));
+    const groupMap = new Map((Array.isArray(groups) ? groups : []).map(g => [g.browser ? `${g.browser}:${g.id}` : g.id, g]));
 
     let tabs = all;
     if (query) tabs = tabs.filter((t) => matchesQuery(t, query));
@@ -45,13 +54,13 @@ export const listTabsTool = {
       tabs = tabs.filter((t) => dupIds.has(t.id));
     }
 
-    // Apply MAX_TAB_LIST limit to prevent token overflow
+    const matched = tabs.length;
     if (tabs.length > MAX_TAB_LIST) {
       tabs = tabs.slice(0, MAX_TAB_LIST);
     }
 
     const histogram = domainHistogram(tabs);
-    const windows = new Set(tabs.map((t) => t.windowId)).size;
+    const windows = new Set(tabs.map((t) => t.browser ? `${t.browser}:${t.windowId}` : t.windowId)).size;
     const dupCount = findDuplicateIds(tabs).length;
 
     return formatTabData({
@@ -63,6 +72,8 @@ export const listTabsTool = {
       duplicates_only,
       windows,
       dupCount,
+      matched,
+      show_urls,
     });
   },
 };

package/tools/live.js

@@ -0,0 +1,17 @@
+import { callExtension } from '../bridge.js';
+
+export async function liveTabs(browser) {
+  const all = await callExtension('query_tabs');
+  if (!browser) return all;
+  return all.filter((t) => (t.browser || '').toLowerCase() === browser.toLowerCase());
+}
+
+// Tab groups are optional: older Firefox has none, and a failure must not hide the tabs.
+export async function liveGroups() {
+  try {
+    const groups = await callExtension('query_groups');
+    return Array.isArray(groups) ? groups : [];
+  } catch {
+    return [];
+  }
+}

package/tools/open-tabs.tool.js

@@ -5,7 +5,7 @@ export const openTabsTool = {
   name: 'open_tabs',
   title: 'Open Tabs',
   description:
-    'Open one or more URLs in new Chrome tabs. This tool allows you to navigate the user to ' +
+    'Open one or more URLs in new browser tabs. This tool allows you to navigate the user to ' +
     'specific web pages or search queries.\n\n' +
     'Examples:\n' +
     '- {"urls": ["https://github.com", "https://youtube.com"]}\n' +
@@ -15,21 +15,23 @@ export const openTabsTool = {
     '  - opened (int): Number of tabs successfully opened',
   annotations: {
     readOnlyHint: false,
-    destructiveHint: false, // opening tabs is non-destructive
+    destructiveHint: false,
     idempotentHint: false,
     openWorldHint: true,
   },
   inputSchema: {
     urls: z.array(z.string()).min(1)
       .describe('An array of URLs to open. If no protocol is provided, https:// will be prepended automatically.'),
+    browser: z.string().optional()
+      .describe('Target browser to open tabs in (e.g. "chrome", "firefox"). Defaults to the active browser.'),
   },
 
-  execute: async ({ urls }) => {
+  execute: async ({ urls, browser }) => {
     if (!urls || urls.length === 0) {
       throw new Error('Provide at least one URL to open.');
     }
 
-    const res = await callExtension('open_tabs', { urls });
+    const res = await callExtension('open_tabs', { urls, browser });
     return JSON.stringify({ opened: res.opened }, null, 2);
   },
 };

package/tools/present.js

@@ -27,7 +27,7 @@ function renderHistogram(histogram) {
   return lines;
 }
 
-function renderByDomain(tabs, groupMap) {
+function renderByDomain(tabs, groupMap, urlLine) {
   const grouped = {};
   for (const t of tabs) {
     const domain = t.url ? new URL(t.url).hostname : '(local)';
@@ -41,7 +41,7 @@ function renderByDomain(tabs, groupMap) {
       const label = tabLabel(t);
       const flags = buildFlags(t);
       const flagStr = formatFlags(flags);
-      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}${urlLine(t)}`);
     }
     lines.push('');
   }
@@ -49,20 +49,23 @@ function renderByDomain(tabs, groupMap) {
   return lines;
 }
 
-function renderByWindow(tabs, groupMap) {
+function renderByWindow(tabs, groupMap, urlLine) {
   const grouped = {};
   for (const t of tabs) {
-    (grouped[t.windowId] ??= []).push(t);
+    const key = t.browser ? `${t.browser}:${t.windowId}` : `${t.windowId}`;
+    (grouped[key] ??= []).push(t);
   }
 
   const lines = [];
-  for (const [winId, tabsInWin] of Object.entries(grouped)) {
-    lines.push(formatWindowHeader(winId, tabsInWin.length));
+  for (const [key, tabsInWin] of Object.entries(grouped)) {
+    const browser = tabsInWin[0]?.browser;
+    const winId = tabsInWin[0]?.windowId ?? key;
+    lines.push(formatWindowHeader(winId, tabsInWin.length, browser));
     for (const t of tabsInWin) {
       const label = tabLabel(t);
       const flags = buildFlags(t);
       const flagStr = formatFlags(flags);
-      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}${urlLine(t)}`);
     }
     lines.push('');
   }
@@ -70,7 +73,7 @@ function renderByWindow(tabs, groupMap) {
   return lines;
 }
 
-function renderFlat(tabs, groupMap) {
+function renderFlat(tabs, groupMap, urlLine) {
   const lines = [];
   for (const t of tabs) {
     const c = compact(t);
@@ -80,7 +83,7 @@ function renderFlat(tabs, groupMap) {
         : c.title;
     const flags = buildFlags(c);
     const flagStr = formatFlags(flags);
-    lines.push(`  · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+    lines.push(`  · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}${urlLine(t)}`);
   }
 
   return lines;
@@ -96,27 +99,41 @@ export function formatTabData(data) {
     duplicates_only,
     windows,
     dupCount,
+    matched = tabs.length,
+    show_urls = false,
   } = data;
 
   const lines = [];
+  const urlLine = (t) => (show_urls ? `\n        ${t.url ?? ''}` : '');
+
+  const browsers = [...new Set(tabs.map((t) => t.browser).filter(Boolean))];
+  const browserSummary = browsers.length > 1
+    ? ` across ${browsers.length} browsers (${browsers.map((b) => `${b}: ${tabs.filter((t) => t.browser === b).length}`).join(', ')}) and`
+    : ' across';
 
   lines.push(
-    `📊 ${tabs.length} tab(s) across ${windows} window(s)` +
+    `📊 ${tabs.length} tab(s)${browserSummary} ${windows} window(s)` +
       (query ? ` matching "${query}"` : '') +
       (duplicates_only ? ' (duplicates only)' : '') +
       (dupCount > 0 ? ` · ${dupCount} duplicate(s) found` : '') +
       '\n',
   );
+  if (matched > tabs.length) {
+    lines.push(
+      `⚠️ Showing the first ${tabs.length} of ${matched} tabs. Counts, histogram and duplicates above ` +
+      'cover only those shown. Narrow with `query` or `browser`, or use cluster_tabs for the whole set.\n',
+    );
+  }
 
   lines.push(...renderHistogram(histogram));
   lines.push('');
 
   if (group_by === 'domain') {
-    lines.push(...renderByDomain(tabs, groupMap));
+    lines.push(...renderByDomain(tabs, groupMap, urlLine));
   } else if (group_by === 'window') {
-    lines.push(...renderByWindow(tabs, groupMap));
+    lines.push(...renderByWindow(tabs, groupMap, urlLine));
   } else {
-    lines.push(...renderFlat(tabs, groupMap));
+    lines.push(...renderFlat(tabs, groupMap, urlLine));
   }
 
   return lines.join('\n');

package/tools/rendering.js

@@ -1,6 +1,3 @@
-/** Rendering adapters for tab display - delegates to dedicated formatters. */
-
-/** Build emoji flags for tab metadata attributes. */
 export function buildFlags(tab) {
   const flags = [];
   if (tab.pinned) flags.push('📌');
@@ -8,41 +5,36 @@ export function buildFlags(tab) {
   return flags;
 }
 
-/** Format emoji flags as display string. */
 export function formatFlags(flags) {
   return flags.length ? ' ' + flags.join('') : '';
 }
 
-/** Draw ASCII histogram bar for a domain count. */
 export function drawBar(count, maxCount, maxWidth) {
   return '▇'.repeat(Math.max(1, Math.round((count / maxCount) * maxWidth)));
 }
 
-/** Draw a single histogram line. */
 export function formatHistogramLine(domain, count, bar) {
   return `  ${bar}  ${domain.padEnd(28)} ${count} tab(s)`;
 }
 
-/** Draw domain header. */
 export function formatDomainHeader(domain, count) {
   return `📁 ${domain} — ${count} tab(s)`;
 }
 
-/** Draw window header. */
-export function formatWindowHeader(winId, count) {
-  return `🪟 Window ${winId} — ${count} tab(s)`;
+export function formatWindowHeader(winId, count, browser) {
+  const browserPrefix = browser ? `[${browser.charAt(0).toUpperCase() + browser.slice(1)}] ` : '';
+  return `🪟 ${browserPrefix}Window ${winId} — ${count} tab(s)`;
 }
 
-/** Draw group prefix. */
 export function formatGroupPrefix(groupMap, tab) {
   if (tab.groupId === undefined || tab.groupId === -1) return '';
-  const g = groupMap.get(tab.groupId);
+  const g = groupMap.get(tab.browser ? `${tab.browser}:${tab.groupId}` : tab.groupId);
   return g ? `[Group: ${g.title || 'Group ' + g.id}] ` : '';
 }
 
-/** Draw the tab's numeric id - every id-based tool (activate_tab, update_tab,
- * get_tab_text, group_tabs, ungroup_tabs, close_tabs' tab_ids mode) needs one,
- * and this is the only place callers can read it from. */
 export function formatIdPrefix(tab) {
+  if (tab.browser) {
+    return `[id:${tab.browser}:${tab.id}] `;
+  }
   return `[id:${tab.id}] `;
 }

package/tools/reopen-tabs.tool.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+import { checkExpectedCount, CONFIRM_COUNT_OVER } from '../lib/tabs.js';
+import { readRecord, reopenCandidates, snapshotDir } from '../lib/snapshots.js';
+import { liveTabs } from './live.js';
+
+const MAX_REOPEN = 100; // more at once can stall a browser; ask for a narrower match
+
+export const reopenTabsTool = {
+  name: 'reopen_tabs',
+  title: 'Reopen Tabs from a Record',
+  description:
+    'Reopen tabs saved by snapshot_tabs that are no longer open, in the browser they came ' +
+    'from. Narrow with `match` (substring of title or URL). Preview with `dry_run` first. ' +
+    `Reopening more than ${CONFIRM_COUNT_OVER} tabs needs \`expected_count\` from the preview, ` +
+    `and at most ${MAX_REOPEN} open per call. Only web and file links are reopened.\n\n` +
+    'Returns JSON: record, dry_run, count (or opened), sample of up to 10 {title, url}.',
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  inputSchema: {
+    record: z.string().optional()
+      .describe('Record name returned by snapshot_tabs, e.g. "tabs-20261012-141500.json". Omit for the newest.'),
+    match: z.string().optional()
+      .describe('Only reopen tabs whose title or URL contains this substring (case-insensitive).'),
+    dry_run: z.boolean().default(false)
+      .describe('Preview what would reopen without opening anything.'),
+    expected_count: z.number().int().min(1).optional()
+      .describe(`The number of tabs the user agreed to reopen, from the preview. Required above ${CONFIRM_COUNT_OVER}.`),
+  },
+
+  execute: async ({ record, match, dry_run, expected_count }) => {
+    const { name, record: rec } = readRecord(snapshotDir(), record);
+    const targets = reopenCandidates(rec, await liveTabs(), match);
+    const sample = targets.slice(0, 10).map(({ title, url }) => ({ title, url }));
+    if (targets.length === 0) {
+      return `Nothing to reopen from ${name}${match ? ` matching "${match}"` : ''}: every such tab is already open.`;
+    }
+    if (dry_run) return JSON.stringify({ record: name, dry_run: true, count: targets.length, sample }, null, 2);
+
+    checkExpectedCount(targets.length, expected_count, 'reopen');
+    if (targets.length > MAX_REOPEN) {
+      throw new Error(`That is ${targets.length} tabs; reopen at most ${MAX_REOPEN} at a time. Use a narrower match.`);
+    }
+
+    const byBrowser = new Map();
+    for (const t of targets) {
+      if (!byBrowser.has(t.browser)) byBrowser.set(t.browser, []);
+      byBrowser.get(t.browser).push(t.url);
+    }
+    let opened = 0;
+    for (const [browser, urls] of byBrowser) {
+      const res = await callExtension('open_tabs', browser ? { urls, browser } : { urls });
+      opened += res?.opened ?? 0;
+    }
+    return JSON.stringify({ record: name, dry_run: false, opened, sample }, null, 2);
+  },
+};

package/tools/snapshot-tabs.tool.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { buildRecord, snapshotDir, writeRecord } from '../lib/snapshots.js';
+import { liveTabs, liveGroups } from './live.js';
+
+export const snapshotTabsTool = {
+  name: 'snapshot_tabs',
+  title: 'Save a Record of Open Tabs',
+  description:
+    'Save a record of every open tab (title, link, window, tab group, pinned, last used) to a ' +
+    'file in this computer\'s app-data folder, before closing anything. Nothing leaves the ' +
+    'computer, and no cookies or typed form text are saved. Call it once at the start of a ' +
+    'clean-up; reopen_tabs can later reopen tabs from the record.\n\n' +
+    'Returns JSON: record (name to pass to reopen_tabs), path, tabs, windows, by_browser, pinned.',
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  inputSchema: {
+    browser: z.string().optional()
+      .describe('Only record this browser ("chrome", "firefox"). Omit to record every connected browser.'),
+  },
+
+  execute: async ({ browser }) => {
+    const tabs = await liveTabs(browser);
+    const record = buildRecord(tabs, await liveGroups());
+    const { name, path } = writeRecord(record, snapshotDir());
+    const byBrowser = {};
+    for (const t of tabs) byBrowser[t.browser ?? 'unknown'] = (byBrowser[t.browser ?? 'unknown'] ?? 0) + 1;
+    return JSON.stringify({
+      record: name,
+      path,
+      tabs: record.tab_count,
+      windows: record.windows.length,
+      by_browser: byBrowser,
+      pinned: tabs.filter((t) => t.pinned).length,
+      for_your_reply: 'Say once that a list of their open tabs was saved first. Give the name or path only if they ask.',
+    }, null, 2);
+  },
+};

package/tools/start-tab-cleanup.tool.js

@@ -0,0 +1,16 @@
+import { cleanupGuide } from '../lib/guide.js';
+
+export const startTabCleanupTool = {
+  name: 'start_tab_cleanup',
+  title: 'Start a Tab Clean-up',
+  description:
+    'Call this first when the user has too many tabs, wants to clean up, close, sort or dedupe ' +
+    'lots of tabs, or feels stuck or stressed about closing them. Returns the step-by-step ' +
+    'method to follow: save a record, sort tabs into clusters, close what the user confirms, ' +
+    'and park the few real to-dos with a next step and a when, in the user\'s own words. ' +
+    'Read-only; it does not touch any tab.',
+  annotations: { readOnlyHint: true, openWorldHint: false },
+  inputSchema: {},
+
+  execute: async () => cleanupGuide(),
+};

package/tools/ungroup-tabs.tool.js

@@ -4,7 +4,7 @@ import { callExtension } from '../bridge.js';
 export const ungroupTabsTool = {
   name: 'ungroup_tabs',
   title: 'Ungroup Tabs',
-  description: 'Remove one or more open Chrome tabs from their current native Tab Groups.',
+  description: 'Remove one or more open tabs from their current native tab groups.',
   annotations: {
     readOnlyHint: false,
     destructiveHint: false,
@@ -12,12 +12,14 @@ export const ungroupTabsTool = {
     openWorldHint: true,
   },
   inputSchema: {
-    tab_ids: z.array(z.number().int()).min(1)
-      .describe('Array of tab IDs to remove from any groups.'),
+    tab_ids: z.array(z.union([z.number().int(), z.string()])).min(1)
+      .describe('Tab IDs to remove from any groups (numbers or composite like "chrome:12").'),
+    browser: z.string().optional()
+      .describe('Optional browser hint ("chrome", "firefox") if ids are numeric.'),
   },
 
-  execute: async ({ tab_ids }) => {
-    const res = await callExtension('ungroup_tabs', { tab_ids });
+  execute: async ({ tab_ids, browser }) => {
+    const res = await callExtension('ungroup_tabs', { tab_ids, browser });
     return JSON.stringify({
       message: `Successfully ungrouped ${res.ungrouped} tab(s).`,
       ungrouped: res.ungrouped,