Skip to content

CLAUDE.md

Latest commit

 

History

History
91 lines (71 loc) · 3.89 KB

CLAUDE.md

File metadata and controls

91 lines (71 loc) · 3.89 KB
Raw

tabb

A CLI and MCP server for managing Chrome browser tabs from the terminal or an AI assistant.

Architecture

Chrome Extension → Native Messaging (stdin/stdout) → Go binary → Unix domain socket ← CLI / MCP clients

  • Extension (extension/): Manifest V3 Chrome extension. Handles Chrome APIs, tabignore filtering. Thin — proxies requests to/from native host.
  • Go binary (cmd/tabb/): Native Messaging host + Unix socket server. Routes messages between extension and CLI/MCP clients.
  • CLI commands: list, show, close — connect to Unix socket.
  • MCP server: tabb mcp — stdio MCP server bridging to Unix socket.

Project Structure

.claude-plugin/
  marketplace.json   # Lists this repo's plugins for /plugin marketplace add
cmd/tabb/            # Go CLI entrypoint
internal/
  native/            # Native Messaging protocol (length-prefixed JSON)
  socket/            # Unix domain socket server
  profile/           # Profile management (profiles.json, resolution)
  protocol/          # Shared message types
extension/
  manifest.json      # Manifest V3
  background.js      # Service worker
  lib/               # Vendored libraries (Readability, Turndown)
plugins/
  tabb/              # Claude Code plugin (installed standalone from marketplace)
    .claude-plugin/
      plugin.json    # Plugin manifest
    .mcp.json        # Auto-wires the tabb MCP server on install
    skills/
      tabb/
        SKILL.md     # Discoverability + usage skill

The Go project and the Claude Code plugin live in the same repo but do not overlap on disk: everything under plugins/tabb/ is what gets copied into a user's ~/.claude/plugins/cache/ when they install the plugin. The Go source, Makefile, and extension/ directory stay out of that cache.

Conventions

  • Go code uses standard library where possible
  • Extension is vanilla JS (no build step)
  • Unix socket path: ~/.tabb/<profileId>.sock (one per browser/profile)
  • Native Messaging host name: com.tabb
  • CLI output: human-readable by default, --json flag for machine-readable
  • show outputs markdown with YAML frontmatter

Commands

  • tabb [--profile <name>] list — list tab metadata
  • tabb [--profile <name>] show <tab-id> — page content as markdown (Readability mode), --raw for full DOM
  • tabb [--profile <name>] focus <tab-id> [--reload] — bring a tab to the foreground, optionally reload
  • tabb [--profile <name>] close <tab-id> — close a tab
  • tabb profiles — list configured profiles and their status
  • tabb mcp — run as MCP stdio server
  • tabb setup — install Native Messaging host manifest and register a profile

Profiles

tabb supports multiple browser profiles and Chrome-based browsers. Each extension installation gets its own named profile. Profile data is stored in ~/.tabb/profiles.json.

  • Socket files: ~/.tabb/<profileId>.sock (one per browser profile; profileId is generated by the extension and sent in the handshake)
  • Browser info: ~/.tabb/<profileId>.browser (written by native host on handshake; two lines: browser name, extension id)
  • Profile resolution: --profile flag > TABB_PROFILE env var > auto-detect (single socket)

Claude Code Plugin

This repo is also a Claude Code plugin marketplace. Users run:

/plugin marketplace add joelhelbling/tabb
/plugin install tabb

The plugin lives entirely under plugins/tabb/ so the Go source and build artifacts don't end up in users' plugin caches. The plugin contributes:

  • The tabb MCP server (via plugins/tabb/.mcp.json) — assumes the tabb binary is on $PATH
  • A tabb skill (via plugins/tabb/skills/tabb/SKILL.md) — makes Claude Code reach for tabb when the user mentions their open browser tabs

Development

  • Load extension unpacked from extension/ directory in Chrome
  • Run go build ./cmd/tabb to build the binary
  • Socket file is created when the extension connects and launches the native host