Firefox Tab Manager

CLI tool to manage Firefox tabs from the terminal — list, open, close, and organize tabs into groups.

Architecture

tabs CLI  →  Unix socket  →  native-host.js  →  Firefox extension  →  browser.tabs API

A Firefox WebExtension connects to a native messaging host, which also listens on a Unix socket at /tmp/firefox-tabmanager.sock. The CLI talks to that socket.

The extension also shows the total tab count as a toolbar badge and the active tab's ID in the tooltip.

Prerequisites

• Node.js
• Firefox
• web-ext for signing: npm install -g web-ext

Install

git clone <this-repo> ~/code/tabmanager
cd ~/code/tabmanager
./install.sh

This does three things:

1. Installs the native messaging manifest to ~/Library/Application Support/Mozilla/NativeMessagingHosts/
2. Symlinks cli/tabs.js to ~/bin/tabs
3. Makes scripts executable

Loading the extension (development)

For quick testing, load temporarily via about:debugging:

1. Open about:debugging#/runtime/this-firefox in Firefox
2. Click "Load Temporary Add-on..."
3. Select extension/manifest.json from this repo

The extension will be removed when Firefox restarts.

Permanent install with web-ext sign

Sign the extension as unlisted (free, no public listing, no review):

1. Create an AMO developer account at https://addons.mozilla.org/developers/
2. Generate API keys at https://addons.mozilla.org/developers/addon/api/key/
3. Sign the extension:

cd extension
web-ext sign --channel=unlisted \
  --api-key=YOUR_JWT_ISSUER \
  --api-secret=YOUR_JWT_SECRET

4. This creates a signed .xpi file in web-ext-artifacts/
5. Install it in Firefox: open about:addons → gear icon → "Install Add-on From File..." → select the .xpi

The extension will now persist across Firefox restarts.

Usage

# List all tabs across all windows (JSON)
tabs list

# Pretty-print with jq
tabs list | jq .

# Get just URLs
tabs list | jq '.windows[].tabs[].url'

# Find active tabs
tabs list | jq '.windows[].tabs[] | select(.active)'

# Find tabs in a specific group
tabs list | jq '.windows[].tabs[] | select(.group)'

# Open a URL
tabs open https://example.com

# Close a tab by ID
tabs close 42

# Close all tabs in a group
tabs close-group 5

# Create a named group from tabs
tabs create-group work 42,43,44

# Add tabs to an existing group
tabs add-to-group 5 45,46

# Remove tabs from their group
tabs remove-from-group 42,43

Output format

tabs list returns JSON with this structure:

{
  "tabCount": 12,
  "windowCount": 2,
  "groupCount": 1,
  "windows": [
    {
      "id": 3,
      "focused": true,
      "tabCount": 8,
      "tabs": [
        {
          "id": 42,
          "title": "GitHub",
          "url": "https://github.com",
          "active": true,
          "pinned": false
        },
        {
          "id": 43,
          "title": "Docs",
          "url": "https://docs.example.com",
          "active": false,
          "pinned": false,
          "group": "Work:5",
          "groupColor": "blue"
        }
      ]
    }
  ]
}

• Tabs without a group omit the group and groupColor fields
• group format is "title:id" (e.g. "Work:5")

Troubleshooting

"cannot connect to native host"

• Is the Firefox extension loaded? Check about:addons
• Check the socket exists: ls -la /tmp/firefox-tabmanager.sock
• Check Firefox console (about:debugging → Inspect) for native messaging errors

"timed out waiting for response"

• The native host may have crashed. Check about:debugging → Inspect the extension for errors
• Try reloading the extension

Extension doesn't connect after install

• Verify the native messaging manifest exists: cat ~/Library/Application\ Support/Mozilla/NativeMessagingHosts/tab_manager.json
• Verify the path in that file points to the correct absolute path of host/native-host.js
• Verify native-host.js is executable: ls -la host/native-host.js