tabctl

タブ制御

tabctl を使ってタブを安全に調査・分析し、要求された場合にのみ、対象を絞った GraphQL ミューテーションを実行してください。

公開ブラウザー API

ブラウザーの状態は現在、GraphQL 経由でのみ公開されています。

• tabctl query '<GRAPHQL>'
• tabctl schema
• tabctl ping
• tabctl history

削除された従来のブラウザーサブコマンド（list、open、close、inspect、report、screenshot、archive、undo など）は使用しないでください。

検出

tabctl schema
tabctl help
tabctl help query

読み取り例

# Windows, tabs, and groups
 tabctl query '{ windows { windowId focused groups { groupId title } tabs { tabId title url groupTitle } } }'

# Paginated tabs
 tabctl query '{ tabs(limit: 20, offset: 0) { total hasMore items { tabId title url } } }'

# Analyze duplicate/stale tabs
 tabctl query '{ analyze(windowId: 123, staleDays: 30) { totalTabs duplicateTabs staleTabs } }'

# Inspect page metadata
 tabctl query 'query { inspectTabs(tabIds: [456], signals: ["page-meta"]) { entries { tabId signals { name valueJson } } } }'

# Inspect selectors with typed attrs and filters
 tabctl query 'query { inspectTabs(windowId: 123, selectors: [{ name: "prices", selector: ".price", attr: "text", all: true, text: "$", textMode: "contains" }, { name: "submit_visible", selector: "#submit", attr: "visible" }, { name: "submit_style", selector: "#submit", attr: "styles", styleProps: ["color", "background-color"] }, { name: "item_count", selector: ".item", attr: "count" }, { name: "email_value", selector: "input[type=email]", attr: "value" }, { name: "tos_checked", selector: "input[name=terms]", attr: "checked" }]) { entries { tabId url signals { name valueJson } } } }'

# Read page content as Markdown
 tabctl query 'query { readTabs(windowId: 123, extract: true, maxChars: 30000) { entries { tabId title url markdown chars truncated extracted cached status emptyReason diagnostics { source sourceHtmlChars sourceTextChars documentReadyState truncatedHtml cachedAt cacheAgeMs } error } } }'

# Build reports
 tabctl query '{ reportTabs(windowId: 123) { entries { tabId title url description } } }'

# Capture screenshots
 tabctl query 'query { captureScreenshots(tabIds: [456], mode: "viewport") { entries { tabId tiles { index width height } } } }'

読み取り専用の抽出に関する注意事項

• readTabs は Kreuzberg の前処理を使用して、メインフレームの HTML を Markdown に変換します。タブごとに status、emptyReason、diagnostics、error を確認してください。キャッシュされたフォールバックでは、プロファイルごとの上限付きの開いているタブのキャッシュが使用されます。このキャッシュは、読み取りの成功、アクティブなタブの切り替え、静止状態のアクティブページによって更新され、status: CACHED、cached: true、および診断情報内のキャッシュの出所が報告されます。
• readTabs v1 は、クロスオリジンの iframe や Shadow DOM をたどりません。スクリプトを実行できない URL は、status: UNSUPPORTED_URL として返されます。
• inspectTabs のセレクター属性には、html、value、count、box、styles、visible、enabled、checked が含まれるようになりました。
• visible は、レンダリングされており、display:none、visibility:hidden、opacity:0 のいずれにも該当しないことを意味します。
• enabled は、要素が無効化されておらず、aria-disabled != "true" であることを意味します。
• checked は、フォームコントロールには input.checked を使用し、それ以外では aria-checked == "true" を使用します。

ミューテーションの例

# Open tabs in a new grouped window
 tabctl query 'mutation { openTabs(urls: ["https://example.com"], group: "Research", newWindow: true) { windowId groupId tabs { tabId url } } }'

# Group and window changes
 tabctl query 'mutation { updateGroup(groupId: 99, title: "Inbox", color: "blue") { groupId title color } }'
 tabctl query 'mutation { assignToGroup(tabIds: [456], groupTitle: "Inbox") { groupId title } }'
 tabctl query 'mutation { ungroupTabs(tabIds: [456]) { tabId groupId } }'
 tabctl query 'mutation { moveGroup(groupId: 99, newWindow: true) { movedToWindowId movedTabs } }'
 tabctl query 'mutation { mergeWindows(fromWindowId: 200, toWindowId: 123, closeSource: true, confirm: true) { movedTabs sourceClosed } }'

# Tab changes
 tabctl query 'mutation { focusTab(tabId: 456) { success } }'
 tabctl query 'mutation { refreshTabs(tabIds: [456]) { refreshedTabs } }'
 tabctl query 'mutation { moveTab(tabIds: [456], windowId: 123, index: 0) { movedTabs } }'

# Destructive actions with undo support
 tabctl query 'mutation { closeTabs(tabIds: [456], confirm: true) { txid closedTabs } }'
 tabctl query 'mutation { archiveTabs(windowId: 123) { txid archivedTabs } }'
 tabctl query 'mutation { deduplicateTabs(windowId: 123, confirm: true) { txid closedTabs } }'
 tabctl query 'mutation { undoAction(latest: true) { txid summary } }'

# Extension reload
 tabctl query 'mutation { reloadExtension { reloading } }'

安全性

• ユーザーが明示的に変更を求めない限り、読み取り専用の GraphQL クエリを優先してください。
• ミューテーションの対象を限定し、元に戻せるようにしてください。利用可能な場合は txid の値を提示してください。
• 対象の指定または確認を明示的に得ることなく、ユーザーのブラウジングセッション全体に対して破壊的なワークフローを実行しないでください。
• ポリシーを遵守してください。保護されたタブはクエリとミューテーションの結果から除外されます。
• 視覚的なコンテキストが必要な場合にのみ、スクリーンショットを使用してください。

便利なコマンド

tabctl ping
tabctl history --limit 10

接続とバージョンの健全性確認には ping を、取り消しトランザクションの検索には history を使用してください。

トラブルシューティング

• tabctl ping --json は、標準のランタイム健全性チェックです。
• tabctl doctor --fix は、ローカルプロファイルの設定と同期のずれを修復します。
• TABCTL_AUTO_SYNC_MODE=release-like tabctl query '{ tabs { total } }' は、ローカルのリリース相当テスト中にランタイムの同期動作を強制します。