Tabby

A fast, keyboard-driven Chrome extension for consolidating, sorting, and pruning your tabs.

Tabby helps you regain control of your browser. With a single shortcut (Ctrl+Shift+K or Cmd+Shift+K), it gathers all your open tabs across all normal windows, removes exact duplicates and blank-tab clutter, sorts them by URL category (host, path, query), and opens a sleek, keyboard-driven review panel to let you prune whatever remains—complete with full session-aware undo.

Tabby is fully private, local-first, and telemetry-free.

Screenshots

A cleanup in the keyboard-driven review — collapse a group with z, filter with /, mark tabs with x, close with Ctrl+Enter, and undo with u:

The full-page review surface — tabs consolidated, de-duplicated, and sorted, with an intact tab group and quiet advisory badges (bookmarked, stale login). The grouped tabs are research on the maintainer's cat, Leo, a silver tabby British shorthair:

The same review UI mounted in Chrome's native side panel, for pruning without leaving the page you're on:

---

Key Features

The Cleanup Pipeline

Tabby's pipeline is divided into three distinct automated stages before presenting the review:

1. Consolidation: Gathers tabs from all normal windows into the currently focused window, moving tab groups as intact units.
2. Deduplication: Merges identical pages (with customizable query parameter stripping and path normalizations) to auto-close exact duplicates while protecting your active, pinned, or audible tabs.
3. Sorting: Organizes remaining tabs lexicographically (Host → Path → Query) to put similar topics together, while maintaining tab group contiguity and protecting pinned tabs at the front.

Keyboard-Driven Review

No mouse required. Tabby provides an extremely fast, vim-inspired keymap to review and prune your tabs:

• j / k — Move the cursor down / up
• g / G — Jump to the top / bottom of the list
• x / Space — Mark / unmark the selected tab for closing
• V (Visual Mode) — Select a range of tabs to bulk-mark with x
• a / A — Mark all / clear all marks in the current view
• / — Filter tabs by title or URL instantly (press Esc to clear)
• Enter — Jump directly to the selected tab, focusing its window
• ⌘+Enter / Ctrl+Enter — Commit and close all marked tabs
• u — Undo the last commit, restoring closed tabs with full browser history
• z — Collapse / expand the tab group under the cursor
• ? — Toggle the keyboard shortcut help cheatsheet
• Esc — Dismiss overlays, visual mode, or active filters

Mouse Interactions

The keyboard model has a full mouse complement: click a row (anywhere but the links) to mark/unmark it for closing, click the page title or host to switch straight to that tab, and hold-drag a box down the list to select a run of rows at once (it auto-scrolls when you drag past the viewport edge, and you can start the drag anywhere — including the empty margins beside the list). Each row also has a × button to close just that tab, and right-clicking a row opens a Tabby menu to close, stash, mark, or jump — acting on your whole selection when you right-click a selected row, or just that one row otherwise. Rows highlight as you hover. Clicking and hovering never move the keyboard cursor, so the two models stay out of each other's way.

Dual Review Surfaces

Tabby's entire interface is built host-agnostically, allowing you to choose how you want to review your tabs from the Options page:

• Full Page (Default): Opens in a dedicated full-browser tab (review.html) for wide, clear, and comprehensive list management.
• Side Panel: Mounts the exact same UI in Chrome's native side panel (sidepanel.html) for a lightweight, side-by-side pruning experience that won't take you away from your current web page. Requires optional sidePanel permission requested on opt-in.

Quiet Close Suggestions

Tabby highlights tabs that are excellent candidates for closure using quiet, dashed hint badges (e.g., duplicated pages, empty/blank tabs, or matching specific staled-state signals). Clicking a badge marks that tab for closing on commit, keeping decisions explicitly in your control.

Robust Group & Pinned Protection

• Tab Groups: Keeps your existing tab groups intact. If grouped tabs are moved during consolidation, they move as a whole unit, preventing group dissolution.
• Audible & Pinned: Pinned tabs and tabs playing audio are never auto-closed or moved unless explicitly requested or configured in options.
• Stranded Auth Warning: Highlights pages that may have expired sessions or stranded authentication sequences.

Local Records Log & Navigation Trace

Tabby includes a local, telemetry-free Records surface. It tracks a log of your recommendations and close history, and features an opt-in navigation trace mode to help you inspect how you arrived at your open tabs and audit your tab patterns over time.

Deep Configuration Options

Fine-tune Tabby's core behavior via the Options page:

• Normalization: Configure trailing-slash stripping, WWW matching, and exact query parameter blocking.
• Custom Tracking Parameters: Edit the blocklist of tracking query parameters (e.g., utm_*, gclid).
• Keep Policies: Set explicit rules for duplicate resolution (e.g., keep oldest, keep newest, keep active).
• Surface Preference: Switch between Full Page or Side Panel review formats.

---

Installation

Load Unpacked (From Source)

1. Clone this repository to your local machine.
2. Install dependencies:

   pnpm install

3. Build the extension for production:

   pnpm build

   This compiles TypeScript, bundles assets, and generates the loadable extension directory under dist/.
4. Open Google Chrome and navigate to chrome://extensions.
5. Enable Developer mode using the toggle in the top-right corner.
6. Click Load unpacked in the top-left corner.
7. Select the dist/ directory from this project.
8. Click the Tabby extension icon or press Ctrl+Shift+K (or Cmd+Shift+K) to execute your first cleanup!

---

Architecture

Tabby is built around a clean, layered architecture designed for strict testability and robust execution:

graph TD
    A[src/core - Pure Logic] -->|Returns Cleanup Plan| B[src/background - MV3 Service Worker]
    B -->|Provides Tab State| A
    B -->|Feeds Data| C[src/view - Reusable Review UI]
    C -->|Triggers Actions| B
    D[src/options - Settings Page] -->|Saves Settings| B

Loading

• src/core/ (Pure Logic): Contains no references to chrome.* APIs. It models URL normalization, deduplication, lexicographical sorting, and plan building. It is 100% unit-tested in Vitest without requiring a browser.
• src/background/ (MV3 Orchestration): Runs as an ephemeral service worker. It captures browser window/tab snapshots, handles global shortcuts and commands, translates declarative cleanup plans into sequential chrome.tabs/chrome.tabGroups calls, and buffers closed tabs for undo.
• src/view/ (Host-Agnostic UI): A reusable Preact component suite that relies entirely on an abstract ReviewTransport interface. This allows the exact same UI to render in src/review/ (Full Page) or src/sidepanel/ (Side Panel) with zero view-logic forks.
• src/shared/ (Common Layer): Standard types, default tracking parameter blocks, and storage schemas shared across all components.

---

Development

pnpm dev        # Starts Vite dev server with Hot Module Replacement (CRXJS)
pnpm build      # Compiles and builds production assets to dist/
pnpm test       # Runs the Vitest test suite (184 unit tests)
pnpm typecheck  # Runs TypeScript compiler diagnostics
pnpm lint       # Enforces ESLint and Prettier standards
pnpm format     # Re-formats code files with Prettier

Note: When running tests, always use pnpm test (or vitest run). Avoid pnpm test run, as Vitest interprets "run" as a search filter and will run zero tests.

For the full design rationale see DESIGN.md, and for the phased execution ledger see PLAN.md.

---

License

This project is licensed under the MIT License.