feat: group multi-browser output by source

- Add browser source grouping metadata to SDK-created tabs, groups,
  list results, and aggregate count results.
- Render grouped local/remote browser tables consistently for clients,
  tabs, groups, windows, sessions, and remote status output.
- Document remote control, auth, HTTP gateway usage, and the refreshed
  project structure in the README.
- Add coverage for grouped output and BrowserCounts browser_groups.
- Bump the Python package, extension manifest, and lockfile to 0.15.6.
- Add a just publish helper for building and publishing release artifacts.

README.md

@@ -1,20 +1,21 @@
 # browser-cli
-Control your real, running browser from the terminal or the Python SDK — no headless browser, no Playwright, no virtual display. Your actual open tabs, windows, and tab groups respond to your commands.
+Control your real, running browser from the terminal, Python SDK, or a trusted remote client — no headless browser, no Playwright, no virtual display. Your actual open tabs, windows, and tab groups respond to your commands.
 
 ---
 
 ## What it does
 You have 40 tabs open. You want to close all the duplicates, group the GitHub ones, save your session before a meeting, and open a few URLs into a specific group — all from a script. That is what browser-cli is for.
 
-It works by pairing a small browser extension with a Python package that provides both a CLI and SDK. The extension has full access to your browser's tabs, windows, groups, and page DOM. The CLI and SDK talk to it in real time over a local IPC channel.
+It works by pairing a small browser extension with a Python package that provides both a CLI and SDK. The extension has full access to your browser's tabs, windows, groups, and page DOM. The CLI and SDK talk to it in real time over a local IPC channel, or through the optional authenticated TCP remote bridge.
 
 ---
 
 ## How it works
 ```
-terminal / python script
+terminal / python script / remote client
         │
         │  Local IPC  (Unix socket on Linux/macOS, named pipe on Windows)
+        │  or TCP remote bridge  (Ed25519 auth, optional compression)
         ▼
   Native Messaging Host  (Python process, launched by the browser)
         │
@@ -33,7 +34,7 @@ terminal / python script
 4. CLI commands connect to that socket, send a JSON command, and wait for the result.
 5. The native host relays the command to the extension via stdout, receives the result via stdin, and sends it back to the CLI.
 
-No server needs to be running beforehand. The browser manages the native host's lifecycle.
+No local server needs to be running beforehand. The browser manages the native host's lifecycle. For cross-machine control, `browser-cli serve` starts an explicit TCP listener protected by Ed25519 public-key authentication unless you opt out with `--no-auth`.
 
 **Message format**
 
@@ -53,7 +54,7 @@ Every response:
 **Requirements:** Python 3.10+, [uv](https://github.com/astral-sh/uv), Chrome, Chromium, Brave, Edge, Vivaldi, or Firefox
 
 ### Install with uv
-Once published on PyPI, install the CLI as a uv tool:
+Install the CLI from PyPI as a uv tool:
 
 ```sh
 uv tool install real-browser-cli
@@ -100,62 +101,42 @@ Only the `browser-cli` command needs to be on your `PATH`. The browser launches
 ```text
 browser-cli/
 ├── browser_cli/
-│   ├── __init__.py        # Python SDK — BrowserCLI class and SDK entry point
-│   ├── cli.py             # Click CLI entry point
-│   ├── client/            # Client-side command routing used by CLI and SDK
-│   │   ├── core.py         # send_command and remote command routing
-│   │   ├── targets.py      # Browser target discovery and socket resolution
-│   │   ├── auth.py         # Remote auth fields and key lookup
-│   │   └── messages.py     # Request/response helpers
-│   ├── models.py          # Tab and Group helper models
-│   ├── native/            # Native messaging host internals
-│   │   ├── host.py         # Browser-launched native host entry point
-│   │   ├── local_server.py # Local CLI IPC server
-│   │   └── protocol.py     # Chrome Native Messaging framing
-│   ├── remote/            # Client-side remote browser support
-│   │   ├── transport.py    # TCP/TLS remote transport
-│   │   └── registry.py     # Saved remote endpoints/keys
-│   └── commands/
-│       ├── navigate.py    # nav open/reload/back/forward/focus
-│       ├── search.py      # search engine shortcuts
-│       ├── tabs.py        # tab management
-│       ├── groups.py      # tab group management
-│       ├── windows.py     # window management
-│       ├── dom.py         # DOM querying and interaction
-│       ├── extract.py     # content extraction
-│       └── session.py     # session save/load
+│   ├── __init__.py          # Public sync SDK: BrowserCLI and namespace wiring
+│   ├── async_sdk.py         # AsyncBrowserCLI
+│   ├── cli.py               # Click root command and native-host entry point
+│   ├── client/              # send_command path, local/remote routing, message helpers
+│   ├── sdk/                 # SDK namespaces: nav, tabs, groups, windows, dom, session, ...
+│   ├── commands/            # CLI presentation layer over the SDK namespaces
+│   ├── native/              # Browser-launched Native Messaging host + local IPC server
+│   ├── remote/              # TCP remote client transport and saved endpoint registry
+│   ├── serve/               # Authenticated TCP server runtime
+│   ├── transport/           # JSON/msgpack response encoding and compression helpers
+│   ├── markdown/            # HTML-to-Markdown extraction helpers
+│   ├── auth/                # Ed25519 keys, signing, SSH-agent/YubiKey helpers, PQ KEX
+│   └── models.py            # Tab, Group, BrowserCounts dataclasses
 ├── extension/
-│   ├── manifest.json      # MV3 extension manifest
-│   ├── content.js         # Content-script helpers
-│   └── src/               # TypeScript source split by command area
-│       ├── index.ts       # Builds generated extension/background.js
-│       └── content/       # Builds generated extension/content-dispatch.js
-├── examples/
-│   ├── demo.py            # Python SDK walkthrough
-│   └── demo.sh            # Bash CLI walkthrough
-├── tests/
-│   ├── conftest.py        # shared pytest fixtures
-│   ├── test_api.py
-│   ├── test_cli.py
-│   ├── test_dom.py
-│   ├── test_extract.py
-│   ├── test_groups.py
-│   ├── test_nav.py
-│   ├── test_session.py
-│   ├── test_tabs.py
-│   └── test_windows.py
-├── com.browsercli.host.json  # native messaging manifest template
-├── pyproject.toml            # package metadata and CLI entry point
-└── uv.lock                   # locked dependencies for uv
+│   ├── manifest.json        # Chromium MV3 manifest
+│   └── src/                 # TypeScript WebExtension source
+│       ├── index.ts         # Background/service-worker bundle entry
+│       ├── content-dispatch.ts
+│       ├── commands/        # Browser-side command implementations
+│       ├── content/         # DOM/extract/Markdown logic injected into pages
+│       └── core/            # Shared extension helpers
+├── examples/                # Python and shell walkthroughs
+├── scripts/                 # Packaging and release helper scripts
+├── tests/                   # pytest suite
+├── package.json             # Extension build/test/package scripts
+├── pyproject.toml           # Python package metadata
+└── uv.lock                  # locked Python dependencies
 ```
 
 ---
 
 ## CLI reference
 
-All commands are run with `uv run browser-cli [--browser ALIAS] <command>`.
+During source development, commands are usually run as `uv run browser-cli [--browser ALIAS] <command>`. After tool installation, use `browser-cli ...` directly. Add `--remote HOST[:PORT]` and optionally `--key PATH` to target a browser exposed by `browser-cli serve`.
 
-If exactly one browser instance is connected, commands auto-target it. Use `--browser ALIAS` when multiple browser instances are connected. `tabs list`, `tabs count`, `groups list`, `groups count`, `windows list`, and `session list` aggregate across all active browsers when `--browser` is omitted; in that mode they show the source browser alias or UUID. You can inspect the active instances with `browser-cli clients` and assign a persistent profile alias from inside the target browser with `browser-cli clients rename --browser <current-alias> <new-alias>`. Closed browsers are removed from the client registry automatically.
+If exactly one browser instance is connected, commands auto-target it. Use `--browser ALIAS` when multiple browser instances are connected. `tabs list`, `tabs count`, `groups list`, `groups count`, `windows list`, and `session list` aggregate across all active browsers when `--browser` is omitted; in that mode they show the source browser alias or UUID. When local and saved remote browsers are mixed, tables group rows by source (`local` or the remote endpoint) and indent the browser profile below that group. You can inspect active instances with `browser-cli clients` and assign a persistent profile alias from inside the target browser with `browser-cli clients rename --browser <current-alias> <new-alias>`. Closed browsers are removed from the client registry automatically.
 
 Important: profile aliases are browser-instance aliases, not window aliases. Window aliases created with `windows rename` are only for targeting windows in commands like `nav open --window work`. If a browser instance has no explicit profile alias set, the native host gives it a generated UUID alias so multiple unaliased browsers stay distinct.
 
@@ -315,6 +296,27 @@ browser-cli completion zsh                   # print setup instructions
 browser-cli completion zsh --script          # output raw completion script
 ```
 
+### Remote control, auth, and gateways
+
+```sh
+# On the machine with the browser
+browser-cli auth keygen --output ~/.config/browser-cli/client.key
+PUBKEY=$(browser-cli auth show --key ~/.config/browser-cli/client.key | tail -n1)
+browser-cli auth trust "$PUBKEY"
+browser-cli serve --host 0.0.0.0 --port 8765 --authorized-keys ~/.config/browser-cli/authorized_keys
+
+# From another machine
+browser-cli --remote browser-host.example:8765 --key ~/.config/browser-cli/client.key tabs list
+browser-cli remote trust browser-host.example:8765 ~/.config/browser-cli/client.key
+browser-cli --remote browser-host.example:8765 clients
+
+# Local HTTP JSON gateway for small integrations
+browser-cli serve-http --port 8766
+curl -H "Authorization: Bearer <token>" http://127.0.0.1:8766/tabs
+```
+
+Remote auth uses Ed25519 challenge/response. `--remote` domains default to port 443; explicit `host:port` endpoints are also supported. Saved remote endpoints participate in aggregate list/count commands, where output is grouped by endpoint.
+
 ---
 
 ## Python SDK
@@ -325,7 +327,7 @@ from browser_cli import AsyncBrowserCLI, BrowserCLI
 b = BrowserCLI()
 ```
 
-Commands are grouped into namespaces on the client (`b.tabs`, `b.dom`, `b.session`, ...). Each sync call blocks until the browser responds and returns the data directly as a Python object. For asyncio programs, `AsyncBrowserCLI` exposes the same namespaces as native awaitable methods over async Unix/TCP transport.
+Commands are grouped into namespaces on the client (`b.tabs`, `b.dom`, `b.session`, ...). Each sync call blocks until the browser responds and returns the data directly as a Python object. Create `BrowserCLI(remote="host:8765", key="client.key")` to target a remote server. For asyncio programs, `AsyncBrowserCLI` exposes the same namespaces as native awaitable methods over async Unix/TCP transport.
 
 ```python
 # Navigation  ── b.nav
@@ -480,6 +482,7 @@ counts = b.tabs.count()
 if isinstance(counts, BrowserCounts):
     print(counts.total)
     print(counts.by_browser)
+    print(counts.browser_groups)  # e.g. {"local:work": "local", "remote:work": "remote"}
 ```
 
 ---
@@ -515,6 +518,7 @@ The extension source lives in `extension/src/`. `extension/background.js` and `e
 Packaging:
 
 ```bash
+just publish                                 # build to /tmp/dist-browser-cli and publish with .env credentials
 npm run package:extension                    # testing/unpacked zip, keeps manifest.key for stable Chromium native-messaging ID
 npm run package:extension:webstore           # Chrome Web Store zip, strips manifest.key
 npm run package:extension:webstore:verified  # Chrome Web Store CRX signed for verified uploads

browser_cli/__init__.py

@@ -36,7 +36,7 @@ Commands are grouped into namespaces on the client:
 """
 from collections.abc import Callable
 
-from browser_cli.client import active_browser_targets, remote_browser_targets, send_command, send_command_async
+from browser_cli.client import active_browser_targets, remote_browser_targets, remote_targets_for_alias, send_command, send_command_async
 from browser_cli.errors import BrowserNotConnected
 from browser_cli.models import BrowserCounts, Group, Tab
 from browser_cli.sdk import (

browser_cli/async_sdk.py

@@ -220,18 +220,40 @@ class AsyncBrowserCLI:
   async def clients(self) -> list[dict]:
     return await self._cmd("clients.list", {})
 
-  def tab_from(self, data: dict, *, browser_profile: str | None = None, browser_name: str | None = None, browser_remote: str | None = None) -> Tab:
+  def tab_from(
+    self,
+    data: dict,
+    *,
+    browser_profile: str | None = None,
+    browser_name: str | None = None,
+    browser_remote: str | None = None,
+    browser_type: str | None = None,
+    browser_group: str | None = None,
+  ) -> Tab:
     return self._sync.tab_from(
       data,
       browser_profile=browser_profile,
       browser_name=browser_name,
       browser_remote=browser_remote,
+      browser_type=browser_type,
+      browser_group=browser_group,
     )
 
-  def group_from(self, data: dict, *, browser_profile: str | None = None, browser_name: str | None = None, browser_remote: str | None = None) -> Group:
+  def group_from(
+    self,
+    data: dict,
+    *,
+    browser_profile: str | None = None,
+    browser_name: str | None = None,
+    browser_remote: str | None = None,
+    browser_type: str | None = None,
+    browser_group: str | None = None,
+  ) -> Group:
     return self._sync.group_from(
       data,
       browser_profile=browser_profile,
       browser_name=browser_name,
       browser_remote=browser_remote,
+      browser_type=browser_type,
+      browser_group=browser_group,
     )

browser_cli/client/__init__.py

@@ -10,6 +10,7 @@ from browser_cli.client.core import (
   remote_browser_targets,
   remote_browser_targets_async,
   remote_target_for_alias,
+  remote_targets_for_alias,
   send_command,
   send_command_async,
 )
@@ -42,6 +43,7 @@ __all__ = [
   "remote_browser_targets",
   "remote_browser_targets_async",
   "remote_target_for_alias",
+  "remote_targets_for_alias",
   "send_command",
   "send_command_async",
 ]

browser_cli/client/core.py

@@ -25,12 +25,16 @@ def _remote_target_items(endpoint: str, items: list[dict] | None) -> list[Browse
   for item in items or []:
     profile = str(item.get("profile") or "default")
     display = str(item.get("displayName") or profile)
+    display_name = _remote_display_name(endpoint, profile, display)
+    browser_name = item.get("browserName") or item.get("name")
     targets.append(
       BrowserTarget(
         profile=profile,
-        display_name=_remote_display_name(endpoint, profile, display),
+        display_name=display_name,
         socket_path="",
         remote=endpoint,
+        browser_name=str(browser_name) if browser_name else None,
+        display_group=display_name.rsplit(":", 1)[0],
       )
     )
   return targets
@@ -52,15 +56,21 @@ def _remote_browser_targets(key=None, *, suppress_pq_warning: bool = False) -> l
       continue
   return targets
 
-def remote_target_for_alias(alias: str | None) -> BrowserTarget | None:
-  """Resolve a user-facing remote alias such as 'host:profile' to a target."""
+def remote_targets_for_alias(alias: str | None, key=None) -> list[BrowserTarget]:
+  """Return remote targets matching a user-facing alias.
+
+  Exact browser aliases such as ``host:profile`` return one target. Endpoint
+  aliases such as ``host`` or ``host:8765`` may return multiple targets, which
+  lets read/list SDK commands fan out while command dispatch can still reject
+  the ambiguous target.
+  """
   if not alias:
-    return None
-  targets = _remote_browser_targets()
+    return []
+  targets = _remote_browser_targets(key=key) if key is not None else _remote_browser_targets()
   for target in targets:
     endpoint_profile = f"{target.remote}:{target.profile}" if target.remote else None
     if alias in {target.display_name, endpoint_profile}:
-      return target
+      return [target]
 
   endpoint_matches = []
   for target in targets:
@@ -69,16 +79,21 @@ def remote_target_for_alias(alias: str | None) -> BrowserTarget | None:
     remote_host, sep, _remote_port = target.remote.rpartition(":")
     if alias == target.remote or (sep and alias == remote_host):
       endpoint_matches.append(target)
-  if len(endpoint_matches) == 1:
-    return endpoint_matches[0]
-  if len(endpoint_matches) > 1:
-    aliases = [target.profile for target in endpoint_matches]
-    endpoint = endpoint_matches[0].remote or alias
+  return endpoint_matches
+
+def remote_target_for_alias(alias: str | None) -> BrowserTarget | None:
+  """Resolve a user-facing remote alias such as 'host:profile' to a target."""
+  matches = remote_targets_for_alias(alias)
+  if len(matches) == 1:
+    return matches[0]
+  if len(matches) > 1:
+    aliases = [target.profile for target in matches]
+    endpoint = matches[0].remote or alias or "remote"
     examples = "\n".join(
       f"  browser-cli --remote {endpoint} --browser {a} ..."
       for a in aliases
     )
-    display_aliases = [target.display_name for target in endpoint_matches]
+    display_aliases = [target.display_name for target in matches]
     shorthand_examples = "\n".join(
       f"  browser-cli --browser {a} ..."
       for a in display_aliases

browser_cli/client/targets.py

@@ -17,6 +17,8 @@ class BrowserTarget:
   display_name: str
   socket_path: str
   remote: str | None = None
+  browser_name: str | None = None
+  display_group: str | None = None
 
 def is_reachable_unix_endpoint(endpoint: str) -> bool:
   """Return True when a Unix socket path exists and accepts connections."""

browser_cli/commands/__init__.py

@@ -22,60 +22,74 @@ tab_option = click.option("--tab", "tab_id", type=int, default=None, help="Tab I
 
 
 def gentle_mode_option(help_text: str):
-    """Reusable ``--gentle-mode`` Click option (throttle mode for large operations)."""
-    return click.option(
-        "--gentle-mode",
-        type=click.Choice(GENTLE_MODES),
-        default="auto",
-        show_default=True,
-        help=help_text,
-    )
+  """Reusable ``--gentle-mode`` Click option (throttle mode for large operations)."""
+  return click.option(
+    "--gentle-mode",
+    type=click.Choice(GENTLE_MODES),
+    default="auto",
+    show_default=True,
+    help=help_text,
+  )
 
 def print_counts(result, noun: str, *, single_suffix: str = "") -> None:
-    """Render a count result.
+  """Render a count result.
 
-    In multi-browser mode (*result* is a :class:`~browser_cli.BrowserCounts`) print a
-    per-browser table with a Total row; otherwise print a single ``N noun(s)`` line.
-    """
-    if isinstance(result, BrowserCounts):
-        table = Table(show_header=True, header_style="bold cyan")
-        table.add_column("Browser")
-        table.add_column(f"{noun.capitalize()}s", justify="right")
-        for name, count in result.by_browser.items():
-            table.add_row(name, str(count))
-        table.add_row("Total", str(result.total))
-        _console.print(table)
-    else:
-        _console.print(f"[bold]{result}[/bold] {noun}(s){single_suffix}")
+  In multi-browser mode (*result* is a :class:`~browser_cli.BrowserCounts`) print a
+  per-browser table with a Total row; otherwise print a single ``N noun(s)`` line.
+  """
+  if isinstance(result, BrowserCounts):
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Browser", no_wrap=True)
+    table.add_column(f"{noun.capitalize()}s", justify="right")
+    rendered_groups: set[str] = set()
+    for name, count in result.by_browser.items():
+      group = result.browser_groups.get(name)
+      if group:
+        if group not in rendered_groups:
+          group_total = sum(
+            browser_count
+            for browser_name, browser_count in result.by_browser.items()
+            if result.browser_groups.get(browser_name) == group
+          )
+          table.add_row(f"[bold]{group}[/bold]", str(group_total))
+          rendered_groups.add(group)
+        display_name = name.removeprefix(f"{group}:")
+        table.add_row(f"  {display_name}", str(count))
+      else:
+        table.add_row(name, str(count))
+    table.add_row("Total", str(result.total))
+    _console.print(table)
+  else:
+    _console.print(f"[bold]{result}[/bold] {noun}(s){single_suffix}")
 
 def client_from_ctx() -> BrowserCLI:
-    """Build a BrowserCLI from the root context's global options.
+  """Build a BrowserCLI from the root context's global options.
 
-    Reads ``browser``/``remote``/``key`` set by the top-level ``main`` group.
-    Falls back to an unconfigured client when a command group is invoked
-    standalone (e.g. in unit tests).
-    """
-    obj = click.get_current_context().find_root().obj or {}
-    return BrowserCLI(browser=obj.get("browser"), remote=obj.get("remote"), key=obj.get("key"))
+  Reads ``browser``/``remote``/``key`` set by the top-level ``main`` group.
+  Falls back to an unconfigured client when a command group is invoked
+  standalone (e.g. in unit tests).
+  """
+  obj = click.get_current_context().find_root().obj or {}
+  return BrowserCLI(browser=obj.get("browser"), remote=obj.get("remote"), key=obj.get("key"))
 
 def handle_errors(fn):
-    """Decorate a CLI command so SDK exceptions become clean errors + exit(1).
+  """Decorate a CLI command so SDK exceptions become clean errors + exit(1).
 
-    Apply as the innermost decorator (directly above ``def``) so Click's option
-    decorators attach their params to the wrapper.
-    """
-    @functools.wraps(fn)
-    def wrapper(*args, **kwargs):
-        try:
-            return fn(*args, **kwargs)
-        except BrowserNotConnected as e:
-            _console.print(f"[red]Error:[/red] {e}")
-            raise SystemExit(1)
-        except PermissionError as e:
-            _console.print(f"[red]Blocked:[/red] {e}")
-            raise SystemExit(1)
-        except RuntimeError as e:
-            _console.print(f"[red]Browser error:[/red] {e}")
-            raise SystemExit(1)
+  Apply as the innermost decorator (directly above ``def``) so Click's option
+  decorators attach their params to the wrapper.
+  """
+  @functools.wraps(fn)
+  def wrapper(*args, **kwargs):
+    try:
+      return fn(*args, **kwargs)
+    except BrowserNotConnected as e:
+      _console.print(f"[red]Error:[/red] {e}")
+      raise SystemExit(1)
+    except PermissionError as e:
+      _console.print(f"[red]Blocked:[/red] {e}")
+      raise SystemExit(1)
+    except RuntimeError as e:
+      _console.print(f"[red]Browser error:[/red] {e}")
+      raise SystemExit(1)
 
-    return wrapper
+  return wrapper

browser_cli/commands/clients.py

@@ -36,7 +36,7 @@ def _ensure_unique_browser_alias(alias: str, target_browser: str | None) -> None
   if alias in profiles and alias != target_profile:
     raise click.ClickException(f"Browser alias '{alias}' already exists")
 
-def _append_clients(into, label, *, profile=None, remote=None, key=None, quiet_remote_warning=False):
+def _append_clients(into, label, *, profile=None, remote=None, key=None, quiet_remote_warning=False, profile_group=None):
   """Query clients.list for one target and append each, tagged with *label*."""
   if quiet_remote_warning:
     result = send_command(
@@ -50,6 +50,8 @@ def _append_clients(into, label, *, profile=None, remote=None, key=None, quiet_r
     result = send_command("clients.list", profile=profile, remote=remote, key=key)
   for c in (result or []):
     c["profile"] = label
+    if profile_group:
+      c["profileGroup"] = profile_group
     into.append(c)
 
 @click.group("clients", invoke_without_command=True)
@@ -89,7 +91,14 @@ def _collect_remote_alias_clients(all_clients: list, browser_alias: str, key) ->
     sys.exit(1)
   for target in targets:
     try:
-      _append_clients(all_clients, target.display_name, profile=target.profile, remote=resolved.remote, key=key)
+      _append_clients(
+        all_clients,
+        target.display_name,
+        profile=target.profile,
+        remote=resolved.remote,
+        key=key,
+        profile_group=target.display_group,
+      )
     except (BrowserNotConnected, RuntimeError):
       continue
 
@@ -109,10 +118,11 @@ def _collect_local_and_saved_remote_clients(all_clients: list) -> None:
   for profile_name, sock_path in profiles.items():
     display_profile = display_browser_name(profile_name, sock_path)
     try:
-      _append_clients(all_clients, display_profile, profile=profile_name)
+      _append_clients(all_clients, display_profile, profile=profile_name, profile_group="local")
     except (BrowserNotConnected, RuntimeError):
       all_clients.append({
         "profile": display_profile,
+        "profileGroup": "local",
         "name": "—",
         "version": "—",
         "extensionVersion": "disconnected",
@@ -130,6 +140,7 @@ def _collect_local_and_saved_remote_clients(all_clients: list) -> None:
         profile=target.profile,
         remote=target.remote,
         quiet_remote_warning=True,
+        profile_group=target.display_group,
       )
     except (BrowserNotConnected, RuntimeError):
       continue
@@ -137,13 +148,25 @@ def _collect_local_and_saved_remote_clients(all_clients: list) -> None:
 def _print_clients(all_clients: list) -> None:
   from rich.table import Table
   table = Table(show_header=True, header_style="bold cyan")
-  table.add_column("Profile")
+  table.add_column("Profile", no_wrap=True)
   table.add_column("Browser")
   table.add_column("Version")
   table.add_column("Extension Version")
+  rendered_groups: set[str] = set()
+  groups = {c.get("profileGroup") for c in all_clients if c.get("profileGroup")}
+  grouped = bool(groups and groups != {"local"})
   for c in all_clients:
+    group = c.get("profileGroup") if grouped else None
+    if group:
+      if group not in rendered_groups:
+        table.add_row(f"[bold]{group}[/bold]", "", "", "")
+        rendered_groups.add(group)
+      profile = str(c.get("profile", "")).removeprefix(f"{group}:")
+      profile = f"  {profile}"
+    else:
+      profile = c.get("profile", "")
     table.add_row(
-      c.get("profile", ""),
+      profile,
       c.get("name", ""),
       c.get("version", ""),
       c.get("extensionVersion", ""),

browser_cli/commands/groups.py

@@ -1,33 +1,19 @@
 import click
 from browser_cli.commands import client_from_ctx, gentle_mode_option, handle_errors, print_counts
+from browser_cli.commands.rendering import print_browser_grouped_table_rows
 from rich.console import Console
-from rich.table import Table
 
 console = Console()
 
 def _print_groups(groups, *, show_browser: bool = False) -> None:
-    if not groups:
-        console.print("[yellow]No groups found[/yellow]")
-        return
-    table = Table(show_header=True, header_style="bold cyan")
-    if show_browser:
-        table.add_column("Browser")
-    table.add_column("ID", style="dim", no_wrap=True)
-    table.add_column("Name")
-    table.add_column("Color", width=10)
-    table.add_column("Collapsed", width=10)
-    table.add_column("Tabs", width=6)
-    for g in groups:
-        row = [
-            (g.browser or "") if show_browser else None,
-            str(g.id),
-            g.title or "",
-            g.color or "",
-            "yes" if g.collapsed else "no",
-            str(g.tab_count),
-        ]
-        table.add_row(*[value for value in row if value is not None])
-    console.print(table)
+    columns = [
+        ("ID", lambda g: g.id),
+        ("Name", lambda g: g.title or ""),
+        ("Color", lambda g: g.color or ""),
+        ("Collapsed", lambda g: "yes" if g.collapsed else "no"),
+        ("Tabs", lambda g: g.tab_count),
+    ]
+    print_browser_grouped_table_rows(groups, columns, console=console, empty_message="[yellow]No groups found[/yellow]")
 
 @click.group("groups")
 def group_group():

browser_cli/commands/remote.py

@@ -8,6 +8,7 @@ from rich.table import Table
 
 from browser_cli import BrowserCLI
 from browser_cli.commands import handle_errors
+from browser_cli.commands.rendering import print_browser_grouped_table_rows
 from browser_cli.remote.registry import REMOTE_REGISTRY_PATH, load_remotes, save_remote_key
 
 console = Console()
@@ -23,14 +24,23 @@ def remote_group():
 def remote_status(endpoint, key):
     """Probe a remote endpoint and show server/client status."""
     client = BrowserCLI(remote=endpoint, key=key)
-    clients = client.clients()
-    table = Table(show_header=True, header_style="bold cyan")
-    table.add_column("Profile")
-    table.add_column("Browser")
-    table.add_column("Extension")
-    for item in clients:
-        table.add_row(str(item.get("profile", "")), str(item.get("name", "")), str(item.get("extensionVersion", "")))
-    console.print(table)
+    clients = [
+        {**item, "profileLabel": item.get("profile", ""), "profileGroup": endpoint}
+        for item in client.clients()
+    ]
+    columns = [
+        ("Browser", lambda item: item.get("name", "")),
+        ("Extension", lambda item: item.get("extensionVersion", "")),
+    ]
+    print_browser_grouped_table_rows(
+        clients,
+        columns,
+        console=console,
+        empty_message="[yellow]No browser clients found[/yellow]",
+        browser_getter=lambda item: item.get("profileLabel", ""),
+        group_getter=lambda item: item.get("profileGroup", ""),
+        browser_header="Profile",
+    )
 
 @remote_group.command("trust")
 @click.argument("endpoint")

browser_cli/commands/rendering.py

@@ -1,187 +0,0 @@
-"""Reusable rendering helpers for CLI command modules."""
-from __future__ import annotations
-
-import shutil
-from collections.abc import Callable, Iterable, Sequence
-from typing import Any
-
-from rich.console import Console
-from rich.table import Table
-from rich.text import Text
-from rich.tree import Tree
-
-Column = tuple[str, Callable[[Any], Any]]
-
-def item_value(item: Any, name: str, default: Any = None) -> Any:
-  """Read *name* from a dict-like or attribute object."""
-  if isinstance(item, dict):
-    return item.get(name, default)
-  return getattr(item, name, default)
-
-def shorten(value: str | None, limit: int) -> str:
-  """Return *value* shortened to *limit* cells-ish, using an ellipsis."""
-  value = value or ""
-  return value if len(value) <= limit else value[:max(0, limit - 1)] + "…"
-
-def terminal_width(console: Console | None = None, *, fallback: int = 120) -> int:
-  """Best-effort terminal width for interactive and redirected output.
-
-  Rich falls back to 80 columns when stdout is redirected. browser-cli output is
-  often piped into files for inspection, so also consult ``shutil``/``COLUMNS``
-  and prefer the wider value.
-  """
-  rich_width = (console.width if console is not None else 0) or 0
-  shell_width = shutil.get_terminal_size((fallback, 20)).columns
-  return max(rich_width, shell_width)
-
-def tree_title_limit(*, console: Console | None = None, show_browser: bool = False, show_urls: bool = False) -> int:
-  """Title width for tree labels, reserving space for branches/IDs/metadata."""
-  reserve = 48 if show_urls else 32
-  if show_browser:
-    reserve += 4
-  return max(50, terminal_width(console) - reserve)
-
-def tree_url_limit(title_limit: int, *, console: Console | None = None) -> int:
-  """URL width for tree labels when URLs are displayed."""
-  return max(35, terminal_width(console) - title_limit - 40)
-
-def no_wrap_text() -> Text:
-  """Text configured for one-line tree labels with edge ellipsis."""
-  return Text(no_wrap=True, overflow="ellipsis")
-
-def tab_tree_label(tab: Any, *, title_limit: int, show_urls: bool = False, url_limit: int = 55) -> Text:
-  """Reusable one-line label for a browser tab in tree views."""
-  label = no_wrap_text()
-  label.append(f"[{item_value(tab, 'id')}] ", style="dim")
-  label.append(shorten(item_value(tab, 'title') or "(untitled)", title_limit))
-  if item_value(tab, "active", False):
-    label.append(" *", style="green")
-  url = item_value(tab, "url")
-  if show_urls and url:
-    label.append(" — ", style="dim")
-    label.append(shorten(url, url_limit), style="dim")
-  return label
-
-def group_tree_label(group_id: int, group: Any, *, title_limit: int) -> Text:
-  """Reusable one-line label for a browser tab group in tree views."""
-  title = item_value(group, "title", "") or f"Group {group_id}"
-  color = item_value(group, "color", "") or "group"
-  count = item_value(group, "tab_count", item_value(group, "tabCount", 0)) or 0
-  collapsed = bool(item_value(group, "collapsed", False))
-  label = no_wrap_text()
-  label.append(shorten(title, title_limit), style="bold")
-  meta = [color]
-  if count:
-    meta.append(f"{count} tab" + ("" if count == 1 else "s"))
-  if collapsed:
-    meta.append("collapsed")
-  label.append(" (" + ", ".join(meta) + ")", style="dim")
-  return label
-
-def tab_sort_key(tab: Any) -> tuple:
-  """Stable tab ordering across multi-browser responses."""
-  group_id = item_value(tab, "group_id", item_value(tab, "groupId"))
-  return (
-    item_value(tab, "browser") or "",
-    item_value(tab, "window_id", item_value(tab, "windowId", 0)),
-    item_value(tab, "index", 0) or 0,
-    group_id if group_id is not None else -1,
-    item_value(tab, "id", 0),
-  )
-
-def print_tree(tree: Tree, *, console: Console | None = None) -> None:
-  """Render a Rich tree using the detected full terminal width."""
-  Console(width=terminal_width(console)).print(tree)
-
-def print_table_rows(
-  rows: Sequence[Any],
-  columns: Sequence[Column],
-  *,
-  console: Console,
-  empty_message: str,
-  show_header: bool = True,
-  header_style: str = "bold cyan",
-) -> None:
-  """Render a small Rich table from arbitrary row objects."""
-  if not rows:
-    console.print(empty_message)
-    return
-  table = Table(show_header=show_header, header_style=header_style)
-  for header, _getter in columns:
-    table.add_column(header)
-  for row in rows:
-    table.add_row(*[str(getter(row) or "") for _header, getter in columns])
-  Console(width=terminal_width(console)).print(table)
-
-def build_tabs_tree(
-  tabs: Iterable[Any],
-  groups: Iterable[Any],
-  *,
-  console: Console,
-  show_urls: bool = False,
-) -> Tree:
-  """Build a browser → window → group/tab tree from tab and group responses."""
-  tabs = sorted(tabs, key=tab_sort_key)
-  show_browser = any(item_value(tab, "browser") for tab in tabs)
-  title_limit = tree_title_limit(console=console, show_browser=show_browser, show_urls=show_urls)
-  url_limit = tree_url_limit(title_limit, console=console)
-  group_info = {
-    (
-      item_value(group, "browser") or "local",
-      item_value(group, "window_id", item_value(group, "windowId")),
-      item_value(group, "id"),
-    ): group
-    for group in groups
-  }
-  root = Tree("[bold]Tabs[/bold]")
-  browser_nodes: dict[str, Tree] = {}
-  window_nodes: dict[tuple[str, int], Tree] = {}
-  group_nodes: dict[tuple[str, int, int], Tree] = {}
-  for tab in tabs:
-    browser_key = item_value(tab, "browser") or "local"
-    browser_node = browser_nodes.get(browser_key)
-    if browser_node is None:
-      browser_node = root.add(Text(browser_key, style="bold cyan")) if show_browser else root
-      browser_nodes[browser_key] = browser_node
-    window_id = item_value(tab, "window_id", item_value(tab, "windowId", 0))
-    window_key = (browser_key, window_id)
-    window_node = window_nodes.get(window_key)
-    if window_node is None:
-      window_node = browser_node.add(f"Window {window_id}")
-      window_nodes[window_key] = window_node
-    group_id = item_value(tab, "group_id", item_value(tab, "groupId"))
-    if group_id is None:
-      window_node.add(tab_tree_label(tab, title_limit=title_limit, show_urls=show_urls, url_limit=url_limit))
-      continue
-    group_key = (browser_key, window_id, group_id)
-    group_node = group_nodes.get(group_key)
-    if group_node is None:
-      group = group_info.get(group_key) or group_info.get((browser_key, None, group_id))
-      group_node = window_node.add(group_tree_label(group_id, group, title_limit=title_limit))
-      group_nodes[group_key] = group_node
-    group_node.add(tab_tree_label(tab, title_limit=title_limit, show_urls=show_urls, url_limit=url_limit))
-  return root
-
-def build_windows_tree(windows: Iterable[dict], tabs: Iterable[Any], *, console: Console) -> Tree:
-  """Build a window → tab tree from window and tab responses."""
-  windows = list(windows)
-  tabs = list(tabs)
-  title_limit = tree_title_limit(console=console, show_browser=any("browser" in w for w in windows), show_urls=True)
-  url_limit = tree_url_limit(title_limit, console=console)
-  root = Tree("[bold]Windows[/bold]")
-  for window in sorted(windows, key=lambda item: (item.get("browser", ""), item.get("id", 0))):
-    window_id = window.get("id")
-    label = f"Window {window_id}"
-    if window.get("alias"):
-      label += f" ({window['alias']})"
-    if window.get("browser"):
-      label = f"{window['browser']}: " + label
-    node = root.add(label)
-    window_tabs = [
-      tab for tab in tabs
-      if item_value(tab, "window_id", item_value(tab, "windowId")) == window_id
-      and (not window.get("browser") or item_value(tab, "browser") == window.get("browser"))
-    ]
-    for tab in sorted(window_tabs, key=lambda item: item_value(item, "index", 0) or 0):
-      node.add(tab_tree_label(tab, title_limit=title_limit, show_urls=True, url_limit=url_limit))
-  return root

browser_cli/commands/rendering/__init__.py

@@ -0,0 +1,60 @@
+"""Reusable rendering helpers for CLI command modules."""
+from browser_cli.commands.rendering.common import (
+  Column,
+  item_value,
+  print_browser_grouped_table_rows,
+  print_table_rows,
+  print_tree,
+  shorten,
+  terminal_width,
+  tree_title_limit,
+  tree_url_limit,
+)
+from browser_cli.commands.rendering.labels import (
+  BROWSER_FAMILY_STYLES,
+  DEFAULT_BROWSER_STYLE,
+  DEFAULT_SCOPE,
+  browser_label_style,
+  group_tree_label,
+  no_wrap_text,
+  scoped_browser_label,
+  tab_tree_label,
+)
+from browser_cli.commands.rendering.tabs_tree import (
+  TabsTreeBuilder,
+  browser_label_key,
+  browser_scope,
+  build_tabs_tree,
+  tab_group_id,
+  tab_sort_key,
+  tab_window_id,
+)
+from browser_cli.commands.rendering.windows_tree import build_windows_tree
+
+__all__ = [
+  "BROWSER_FAMILY_STYLES",
+  "Column",
+  "DEFAULT_BROWSER_STYLE",
+  "DEFAULT_SCOPE",
+  "TabsTreeBuilder",
+  "browser_label_key",
+  "browser_label_style",
+  "browser_scope",
+  "build_tabs_tree",
+  "build_windows_tree",
+  "group_tree_label",
+  "item_value",
+  "no_wrap_text",
+  "print_browser_grouped_table_rows",
+  "print_table_rows",
+  "print_tree",
+  "scoped_browser_label",
+  "shorten",
+  "tab_group_id",
+  "tab_sort_key",
+  "tab_tree_label",
+  "tab_window_id",
+  "terminal_width",
+  "tree_title_limit",
+  "tree_url_limit",
+]

browser_cli/commands/rendering/common.py

@@ -0,0 +1,137 @@
+"""Common Rich rendering helpers for CLI command modules."""
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable, Mapping, Sequence
+from typing import TypeVar, cast
+
+from rich.console import Console
+from rich.table import Table
+from rich.tree import Tree
+
+Row = object
+CellValue = object
+Column = tuple[str, Callable[[Row], CellValue]]
+T = TypeVar("T")
+
+
+def item_value(item: Row, name: str, default: T | None = None) -> CellValue | T | None:
+  """Read *name* from a dict-like or attribute object."""
+  if isinstance(item, Mapping):
+    return cast(Mapping[str, CellValue], item).get(name, default)
+  return getattr(item, name, default)
+
+def text_value(value: CellValue | None, default: str = "") -> str:
+  """Coerce a nullable cell value to display text."""
+  return default if value is None else str(value)
+
+def int_value(value: CellValue | None, default: int = 0) -> int:
+  """Coerce a cell value to int, falling back when conversion is not possible."""
+  try:
+    return int(cast(int | str | float | bool, value))
+  except (TypeError, ValueError):
+    return default
+
+def shorten(value: str | None, limit: int) -> str:
+  """Return *value* shortened to *limit* cells-ish, using an ellipsis."""
+  value = value or ""
+  return value if len(value) <= limit else value[:max(0, limit - 1)] + "…"
+
+def terminal_width(console: Console | None = None, *, fallback: int = 120) -> int:
+  """Best-effort terminal width for interactive and redirected output.
+
+  Rich falls back to 80 columns when stdout is redirected. browser-cli output is
+  often piped into files for inspection, so also consult ``shutil``/``COLUMNS``
+  and prefer the wider value.
+  """
+  rich_width = (console.width if console is not None else 0) or 0
+  shell_width = shutil.get_terminal_size((fallback, 20)).columns
+  return max(rich_width, shell_width)
+
+def tree_title_limit(*, console: Console | None = None, show_browser: bool = False, show_urls: bool = False) -> int:
+  """Title width for tree labels, reserving space for branches/IDs/metadata."""
+  reserve = 48 if show_urls else 32
+  if show_browser:
+    reserve += 4
+  return max(50, terminal_width(console) - reserve)
+
+def tree_url_limit(title_limit: int, *, console: Console | None = None) -> int:
+  """URL width for tree labels when URLs are displayed."""
+  return max(35, terminal_width(console) - title_limit - 40)
+
+def print_tree(tree: Tree, *, console: Console | None = None) -> None:
+  """Render a Rich tree using the detected full terminal width."""
+  Console(width=terminal_width(console)).print(tree)
+
+def print_table_rows(
+  rows: Sequence[Row],
+  columns: Sequence[Column],
+  *,
+  console: Console,
+  empty_message: str,
+  show_header: bool = True,
+  header_style: str = "bold cyan",
+) -> None:
+  """Render a small Rich table from arbitrary row objects."""
+  if not rows:
+    console.print(empty_message)
+    return
+  table = Table(show_header=show_header, header_style=header_style)
+  for header, _getter in columns:
+    table.add_column(header)
+  for row in rows:
+    table.add_row(*[text_value(getter(row)) for _header, getter in columns])
+  Console(width=terminal_width(console)).print(table)
+
+def print_browser_grouped_table_rows(
+  rows: Sequence[Row],
+  columns: Sequence[Column],
+  *,
+  console: Console,
+  empty_message: str,
+  browser_getter: Callable[[Row], CellValue | None] = lambda row: item_value(row, "browser"),
+  group_getter: Callable[[Row], CellValue | None] = lambda row: item_value(row, "browser_group", item_value(row, "browserGroup")),
+  browser_header: str = "Browser",
+  show_header: bool = True,
+  header_style: str = "bold cyan",
+) -> None:
+  """Render rows with optional local/remote browser grouping.
+
+  Rows without a browser label are rendered as a normal table. Rows with
+  ``browser_group``/``browserGroup`` get a group header (for example ``local``
+  or a remote host) and a short indented profile label below it.
+  """
+  if not rows:
+    console.print(empty_message)
+    return
+
+  show_browser = any(bool(browser_getter(row)) for row in rows)
+  if not show_browser:
+    print_table_rows(
+      rows,
+      columns,
+      console=console,
+      empty_message=empty_message,
+      show_header=show_header,
+      header_style=header_style,
+    )
+    return
+
+  table = Table(show_header=show_header, header_style=header_style)
+  table.add_column(browser_header, no_wrap=True)
+  for header, _getter in columns:
+    table.add_column(header)
+
+  rendered_groups: set[str] = set()
+  for row in rows:
+    browser = text_value(browser_getter(row))
+    group = text_value(group_getter(row))
+    if group:
+      if group not in rendered_groups:
+        table.add_row(f"[bold]{group}[/bold]", *["" for _header, _getter in columns])
+        rendered_groups.add(group)
+      browser = browser.removeprefix(f"{group}:")
+      browser = f"  {browser}"
+    table.add_row(browser, *[text_value(getter(row)) for _header, getter in columns])
+
+  Console(width=terminal_width(console)).print(table)

browser_cli/commands/rendering/labels.py

@@ -0,0 +1,63 @@
+"""Rich label helpers for tab/window tree renderers."""
+from __future__ import annotations
+
+from rich.text import Text
+
+from browser_cli.commands.rendering.common import Row, int_value, item_value, shorten, text_value
+
+BROWSER_FAMILY_STYLES = {
+  "firefox": "orange1",
+  "chrome": "cyan",
+  "chromium": "cyan",
+  "brave": "cyan",
+  "edge": "cyan",
+  "vivaldi": "cyan",
+}
+DEFAULT_SCOPE = "local"
+DEFAULT_BROWSER_STYLE = "bold cyan"
+
+def no_wrap_text() -> Text:
+  """Text configured for one-line tree labels with edge ellipsis."""
+  return Text(no_wrap=True, overflow="ellipsis")
+
+def tab_tree_label(tab: Row, *, title_limit: int, show_urls: bool = False, url_limit: int = 55) -> Text:
+  """Reusable one-line label for a browser tab in tree views."""
+  label = no_wrap_text()
+  label.append(f"[{text_value(item_value(tab, 'id'))}] ", style="dim")
+  label.append(shorten(text_value(item_value(tab, 'title'), "(untitled)") or "(untitled)", title_limit))
+  if bool(item_value(tab, "active", False)):
+    label.append(" *", style="green")
+  url = text_value(item_value(tab, "url"))
+  if show_urls and url:
+    label.append(" — ", style="dim")
+    label.append(shorten(url, url_limit), style="dim")
+  return label
+
+def group_tree_label(group_id: object, group: Row | None, *, title_limit: int) -> Text:
+  """Reusable one-line label for a browser tab group in tree views."""
+  title = text_value(item_value(group, "title", "") if group is not None else "") or f"Group {group_id}"
+  color = text_value(item_value(group, "color", "") if group is not None else "") or "group"
+  count = int_value(item_value(group, "tab_count", item_value(group, "tabCount", 0)) if group is not None else 0)
+  collapsed = bool(item_value(group, "collapsed", False)) if group is not None else False
+  label = no_wrap_text()
+  label.append(shorten(title, title_limit), style="bold")
+  meta = [color]
+  if count:
+    meta.append(f"{count} tab" + ("" if count == 1 else "s"))
+  if collapsed:
+    meta.append("collapsed")
+  label.append(" (" + ", ".join(meta) + ")", style="dim")
+  return label
+
+def browser_label_style(browser_name: str | None) -> str:
+  """Return a Rich style for a browser family label."""
+  name = (browser_name or "").lower()
+  for family, style in BROWSER_FAMILY_STYLES.items():
+    if family in name:
+      return style
+  return DEFAULT_BROWSER_STYLE
+
+def scoped_browser_label(browser: str, scope: str, *, grouped: bool) -> str:
+  """Shorten browser labels under a remote/local group node."""
+  prefix = f"{scope}:"
+  return browser[len(prefix):] if grouped and browser.startswith(prefix) else browser

browser_cli/commands/rendering/tabs_tree.py

@@ -0,0 +1,185 @@
+"""Tabs tree renderer."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from rich.console import Console
+from rich.text import Text
+from rich.tree import Tree
+
+from browser_cli.commands.rendering.common import Row, int_value, item_value, text_value, tree_title_limit, tree_url_limit
+from browser_cli.commands.rendering.labels import (
+  DEFAULT_BROWSER_STYLE,
+  DEFAULT_SCOPE,
+  browser_label_style,
+  group_tree_label,
+  scoped_browser_label,
+  tab_tree_label,
+)
+
+GroupId = object
+GroupKey = tuple[str, str, int | None, GroupId]
+TreeNodeKey = tuple[str, str]
+WindowNodeKey = tuple[str, str, int]
+BrowserGroupNodeKey = tuple[str, str, int, GroupId]
+
+def browser_scope(item: Row) -> str:
+  """Return the remote/local scope key used by tree renderers."""
+  return text_value(item_value(item, "browser_group")) or DEFAULT_SCOPE
+
+def browser_label_key(item: Row) -> str:
+  """Return the browser/profile key used by tree renderers."""
+  return text_value(item_value(item, "browser")) or DEFAULT_SCOPE
+
+def tab_window_id(tab: Row) -> int:
+  """Return a stable window id from object or dict-shaped tab responses."""
+  return int_value(item_value(tab, "window_id", item_value(tab, "windowId", 0)))
+
+def tab_group_id(tab: Row) -> GroupId | None:
+  """Return a tab group id from object or dict-shaped tab responses."""
+  group_id = item_value(tab, "group_id", item_value(tab, "groupId"))
+  return None if group_id is None else group_id
+
+def tab_sort_key(tab: Row) -> tuple[str, str, int, int, int, int]:
+  """Stable tab ordering across multi-browser responses."""
+  group_id = tab_group_id(tab)
+  return (
+    browser_scope(tab),
+    browser_label_key(tab),
+    tab_window_id(tab),
+    int_value(item_value(tab, "index", 0)),
+    int_value(group_id, -1) if group_id is not None else -1,
+    int_value(item_value(tab, "id", 0)),
+  )
+
+class TabsTreeBuilder:
+  """Stateful builder for the browser tabs tree.
+
+  The tree has optional scope nodes (remote host/local), then browser/profile,
+  then window, then browser tab-groups/tabs. Keeping this state in a helper
+  keeps ``build_tabs_tree`` small while preserving stable node reuse.
+  """
+
+  tabs: list[Row]
+  groups: list[Row]
+  show_urls: bool
+  show_browser: bool
+  group_by_scope: bool
+  title_limit: int
+  url_limit: int
+  root: Tree
+  group_info: dict[GroupKey, Row]
+  browser_styles: dict[str, str]
+  scope_nodes: dict[str, Tree]
+  browser_nodes: dict[TreeNodeKey, Tree]
+  window_nodes: dict[WindowNodeKey, Tree]
+  group_nodes: dict[BrowserGroupNodeKey, Tree]
+
+  def __init__(
+    self,
+    tabs: Iterable[Row],
+    groups: Iterable[Row],
+    *,
+    console: Console,
+    show_urls: bool = False,
+  ):
+    self.tabs = sorted(tabs, key=tab_sort_key)
+    self.groups = list(groups)
+    self.show_urls = show_urls
+    self.show_browser = any(bool(item_value(tab, "browser")) for tab in self.tabs)
+    self.group_by_scope = any(bool(item_value(item, "browser_group")) for item in self.tabs + self.groups)
+    self.title_limit = tree_title_limit(console=console, show_browser=self.show_browser, show_urls=show_urls)
+    self.url_limit = tree_url_limit(self.title_limit, console=console)
+    self.root = Tree("[bold]Tabs[/bold]")
+    self.group_info = self._group_info()
+    self.browser_styles = self._browser_styles()
+    self.scope_nodes = {}
+    self.browser_nodes = {}
+    self.window_nodes = {}
+    self.group_nodes = {}
+
+  def build(self) -> Tree:
+    for tab in self.tabs:
+      self._add_tab(tab)
+    return self.root
+
+  def _group_info(self) -> dict[GroupKey, Row]:
+    return {
+      (
+        browser_scope(group),
+        browser_label_key(group),
+        int_value(item_value(group, "window_id", item_value(group, "windowId")), 0),
+        item_value(group, "id"),
+      ): group
+      for group in self.groups
+    }
+
+  def _browser_styles(self) -> dict[str, str]:
+    styles: dict[str, str] = {}
+    for item in self.tabs + self.groups:
+      key = browser_label_key(item)
+      styles.setdefault(key, browser_label_style(text_value(item_value(item, "browser_name")) or None))
+    return styles
+
+  def _scope_node(self, scope: str) -> Tree:
+    if not self.group_by_scope:
+      return self.root
+    node = self.scope_nodes.get(scope)
+    if node is None:
+      node = self.root.add(Text(scope, style="bold"))
+      self.scope_nodes[scope] = node
+    return node
+
+  def _browser_node(self, scope: str, browser: str) -> Tree:
+    key = (scope, browser)
+    node = self.browser_nodes.get(key)
+    if node is None:
+      parent = self._scope_node(scope)
+      if self.show_browser:
+        label = scoped_browser_label(browser, scope, grouped=self.group_by_scope)
+        node = parent.add(Text(label, style=self.browser_styles.get(browser, DEFAULT_BROWSER_STYLE)))
+      else:
+        node = parent
+      self.browser_nodes[key] = node
+    return node
+
+  def _window_node(self, scope: str, browser: str, window_id: int) -> Tree:
+    key = (scope, browser, window_id)
+    node = self.window_nodes.get(key)
+    if node is None:
+      node = self._browser_node(scope, browser).add(f"Window {window_id}")
+      self.window_nodes[key] = node
+    return node
+
+  def _group_node(self, scope: str, browser: str, window_id: int, group_id: GroupId, parent: Tree) -> Tree:
+    key = (scope, browser, window_id, group_id)
+    node = self.group_nodes.get(key)
+    if node is None:
+      group = self.group_info.get(key) or self.group_info.get((scope, browser, None, group_id))
+      node = parent.add(group_tree_label(group_id, group, title_limit=self.title_limit))
+      self.group_nodes[key] = node
+    return node
+
+  def _add_tab(self, tab: Row) -> None:
+    scope = browser_scope(tab)
+    browser = browser_label_key(tab)
+    window_id = tab_window_id(tab)
+    window_node = self._window_node(scope, browser, window_id)
+    group_id = tab_group_id(tab)
+    parent = window_node if group_id is None else self._group_node(scope, browser, window_id, group_id, window_node)
+    parent.add(tab_tree_label(
+      tab,
+      title_limit=self.title_limit,
+      show_urls=self.show_urls,
+      url_limit=self.url_limit,
+    ))
+
+def build_tabs_tree(
+  tabs: Iterable[Row],
+  groups: Iterable[Row],
+  *,
+  console: Console,
+  show_urls: bool = False,
+) -> Tree:
+  """Build a remote/local → browser → window → group/tab tree from tab responses."""
+  return TabsTreeBuilder(tabs, groups, console=console, show_urls=show_urls).build()

browser_cli/commands/rendering/windows_tree.py

@@ -0,0 +1,38 @@
+"""Windows tree renderer."""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from rich.console import Console
+from rich.tree import Tree
+
+from browser_cli.commands.rendering.common import Row, int_value, item_value, text_value, tree_title_limit, tree_url_limit
+from browser_cli.commands.rendering.labels import tab_tree_label
+
+WindowRow = Mapping[str, object]
+
+def build_windows_tree(windows: Iterable[WindowRow], tabs: Iterable[Row], *, console: Console) -> Tree:
+  """Build a window → tab tree from window and tab responses."""
+  windows = list(windows)
+  tabs = list(tabs)
+  title_limit = tree_title_limit(console=console, show_browser=any("browser" in w for w in windows), show_urls=True)
+  url_limit = tree_url_limit(title_limit, console=console)
+  root = Tree("[bold]Windows[/bold]")
+  for window in sorted(windows, key=lambda item: (text_value(item.get("browser")), int_value(item.get("id")))):
+    window_id = int_value(window.get("id"))
+    label = f"Window {window_id}"
+    alias = text_value(window.get("alias"))
+    browser = text_value(window.get("browser"))
+    if alias:
+      label += f" ({alias})"
+    if browser:
+      label = f"{browser}: " + label
+    node = root.add(label)
+    window_tabs = [
+      tab for tab in tabs
+      if int_value(item_value(tab, "window_id", item_value(tab, "windowId"))) == window_id
+      and (not browser or text_value(item_value(tab, "browser")) == browser)
+    ]
+    for tab in sorted(window_tabs, key=lambda item: int_value(item_value(item, "index", 0))):
+      node.add(tab_tree_label(tab, title_limit=title_limit, show_urls=True, url_limit=url_limit))
+  return root

browser_cli/commands/session.py

@@ -105,24 +105,20 @@ def session_diff(name_a, name_b):
 def session_list():
     """List all saved sessions."""
     from datetime import datetime
-    from rich.table import Table
+    from browser_cli.commands.rendering import print_browser_grouped_table_rows
     sessions = client_from_ctx().session.list()
     if not sessions:
         console.print("[yellow]No saved sessions[/yellow]")
         return
-    show_browser = any("browser" in s for s in sessions)
-    table = Table(show_header=True, header_style="bold cyan")
-    if show_browser:
-        table.add_column("Browser")
-    table.add_column("Name")
-    table.add_column("Tabs", width=6)
-    table.add_column("Saved at")
-    for s in sessions:
-        saved = datetime.fromtimestamp(s["savedAt"] / 1000).strftime("%Y-%m-%d %H:%M") if s.get("savedAt") else ""
-        row = [s.get("browser", "")] if show_browser else []
-        row.extend([s["name"], str(s["tabs"]), saved])
-        table.add_row(*row)
-    console.print(table)
+    def saved_at(session):
+        return datetime.fromtimestamp(session["savedAt"] / 1000).strftime("%Y-%m-%d %H:%M") if session.get("savedAt") else ""
+
+    columns = [
+        ("Name", lambda session: session["name"]),
+        ("Tabs", lambda session: session["tabs"]),
+        ("Saved at", saved_at),
+    ]
+    print_browser_grouped_table_rows(sessions, columns, console=console, empty_message="[yellow]No saved sessions[/yellow]")
 
 @session_group.command("remove")
 @click.argument("name")

browser_cli/commands/tabs.py

@@ -2,25 +2,22 @@ import base64
 import binascii
 import click
 from browser_cli.commands import client_from_ctx, gentle_mode_option, handle_errors, print_counts, tab_option
-from browser_cli.commands.rendering import build_tabs_tree, print_table_rows, print_tree
+from browser_cli.commands.rendering import build_tabs_tree, print_browser_grouped_table_rows, print_tree
 from rich.console import Console
 from rich.table import Table
 
 console = Console()
 
 def _print_tabs(tabs, *, show_browser: bool = False) -> None:
-  columns = []
-  if show_browser:
-    columns.append(("Browser", lambda tab: tab.browser or ""))
-  columns.extend([
+  columns = [
     ("ID", lambda tab: tab.id),
     ("Window", lambda tab: tab.window_id),
     ("Active", lambda tab: "[green]✓[/green]" if tab.active else ""),
     ("Muted", lambda tab: "[yellow]✓[/yellow]" if tab.muted else ""),
     ("Title", lambda tab: (tab.title or "")[:60]),
     ("URL", lambda tab: (tab.url or "")[:80]),
-  ])
-  print_table_rows(tabs, columns, console=console, empty_message="[yellow]No tabs found[/yellow]")
+  ]
+  print_browser_grouped_table_rows(tabs, columns, console=console, empty_message="[yellow]No tabs found[/yellow]")
 
 @click.group("tabs")
 def tabs_group():

browser_cli/commands/windows.py

@@ -1,21 +1,18 @@
 import click
 from browser_cli.commands import client_from_ctx, handle_errors
-from browser_cli.commands.rendering import build_windows_tree, print_table_rows, print_tree
+from browser_cli.commands.rendering import build_windows_tree, print_browser_grouped_table_rows, print_tree
 from rich.console import Console
 
 console = Console()
 
 def _print_windows(windows: list[dict], *, show_browser: bool = False) -> None:
-  columns = []
-  if show_browser:
-    columns.append(("Browser", lambda window: window.get("browser", "")))
-  columns.extend([
+  columns = [
     ("ID", lambda window: window.get("id", "")),
     ("Alias", lambda window: window.get("alias") or ""),
     ("Tabs", lambda window: window.get("tabCount", "")),
     ("State", lambda window: window.get("state") or ""),
-  ])
-  print_table_rows(windows, columns, console=console, empty_message="[yellow]No windows found[/yellow]")
+  ]
+  print_browser_grouped_table_rows(windows, columns, console=console, empty_message="[yellow]No windows found[/yellow]")
 
 @click.group("windows")
 def windows_group():

browser_cli/models.py

@@ -31,6 +31,7 @@ class BrowserCounts:
   """Aggregated per-browser counts returned in implicit multi-browser mode."""
   total: int
   by_browser: dict[str, int]
+  browser_groups: dict[str, str] = field(default_factory=dict)
 
 # ── Tab ───────────────────────────────────────────────────────────────────────
 
@@ -46,6 +47,8 @@ class Tab:
   group_id: int | None = None
   index: int = 0
   browser: str | None = None
+  browser_name: str | None = None
+  browser_group: str | None = None
   _browser: BoundBrowser | None = field(default=None, repr=False, compare=False, init=False)
 
   def _b(self) -> BoundBrowser:
@@ -152,6 +155,8 @@ class Group:
   tab_count: int
   window_id: int | None = None
   browser: str | None = None
+  browser_name: str | None = None
+  browser_group: str | None = None
   _browser: BoundBrowser | None = field(default=None, repr=False, compare=False, init=False)
 
   def _b(self) -> BoundBrowser:

browser_cli/sdk/factories.py

@@ -11,95 +11,114 @@ from typing import Any, Protocol, cast
 
 from browser_cli.models import Group, Tab
 
+def _target_group(target) -> str | None:
+  if target is None:
+    return None
+  return getattr(target, "display_group", None) or ("local" if target.remote is None else None)
+
 class _FactoryClient(Protocol):
-    _key: str | None
+  _key: str | None
 
 class FactoryMixin:
-    """Turn raw response dicts into bound ``Tab``/``Group`` objects.
+  """Turn raw response dicts into bound ``Tab``/``Group`` objects.
 
-    Mixed into :class:`~browser_cli.BrowserCLI`; relies on the client providing
-    ``_browser``/``_remote``/``_key`` and being constructible via ``type(self)``.
-    """
+  Mixed into :class:`~browser_cli.BrowserCLI`; relies on the client providing
+  ``_browser``/``_remote``/``_key`` and being constructible via ``type(self)``.
+  """
 
-    def tab_from(
-        self,
-        data: dict,
-        *,
-        browser_profile: str | None = None,
-        browser_name: str | None = None,
-        browser_remote: str | None = None,
-    ) -> Tab:
-        tab = Tab(
-            id=data["id"],
-            window_id=data.get("windowId", 0),
-            active=data.get("active", False),
-            muted=data.get("muted", False),
-            title=data.get("title") or "",
-            url=data.get("url") or "",
-            group_id=data.get("groupId") or None,
-            index=data.get("index", 0) or 0,
-            browser=browser_name,
-        )
-        client = cast(_FactoryClient, self)
-        tab._browser = self if browser_profile is None else cast(Any, type(self))(
-            browser=browser_profile,
-            remote=browser_remote,
-            key=client._key,
-            _command_sender=getattr(self, "_command_sender", None),
-        )
-        return tab
+  def tab_from(
+    self,
+    data: dict,
+    *,
+    browser_profile: str | None = None,
+    browser_name: str | None = None,
+    browser_remote: str | None = None,
+    browser_type: str | None = None,
+    browser_group: str | None = None,
+  ) -> Tab:
+    tab = Tab(
+      id=data["id"],
+      window_id=data.get("windowId", 0),
+      active=data.get("active", False),
+      muted=data.get("muted", False),
+      title=data.get("title") or "",
+      url=data.get("url") or "",
+      group_id=data.get("groupId") or None,
+      index=data.get("index", 0) or 0,
+      browser=browser_name,
+      browser_name=browser_type,
+      browser_group=browser_group,
+    )
+    client = cast(_FactoryClient, self)
+    tab._browser = self if browser_profile is None else cast(Any, type(self))(
+      browser=browser_profile,
+      remote=browser_remote,
+      key=client._key,
+      _command_sender=getattr(self, "_command_sender", None),
+    )
+    return tab
 
-    def require_tab_response(self, data, error: str) -> Tab:
-        """Build a bound Tab from a tab-shaped response, or raise ``RuntimeError(error)``."""
-        if not isinstance(data, dict) or "id" not in data:
-            raise RuntimeError(error)
-        return self.tab_from(data)
+  def require_tab_response(self, data, error: str) -> Tab:
+    """Build a bound Tab from a tab-shaped response, or raise ``RuntimeError(error)``."""
+    if not isinstance(data, dict) or "id" not in data:
+      raise RuntimeError(error)
+    return self.tab_from(data)
 
-    def group_from(
-        self,
-        data: dict,
-        *,
-        browser_profile: str | None = None,
-        browser_name: str | None = None,
-        browser_remote: str | None = None,
-    ) -> Group:
-        group = Group(
-            id=data["id"],
-            title=data.get("title") or "",
-            color=data.get("color") or "",
-            collapsed=data.get("collapsed", False),
-            tab_count=data.get("tabCount", 0),
-            window_id=data.get("windowId"),
-            browser=browser_name,
-        )
-        client = cast(_FactoryClient, self)
-        group._browser = self if browser_profile is None else cast(Any, type(self))(
-            browser=browser_profile,
-            remote=browser_remote,
-            key=client._key,
-            _command_sender=getattr(self, "_command_sender", None),
-        )
-        return group
+  def group_from(
+    self,
+    data: dict,
+    *,
+    browser_profile: str | None = None,
+    browser_name: str | None = None,
+    browser_remote: str | None = None,
+    browser_type: str | None = None,
+    browser_group: str | None = None,
+  ) -> Group:
+    group = Group(
+      id=data["id"],
+      title=data.get("title") or "",
+      color=data.get("color") or "",
+      collapsed=data.get("collapsed", False),
+      tab_count=data.get("tabCount", 0),
+      window_id=data.get("windowId"),
+      browser=browser_name,
+      browser_name=browser_type,
+      browser_group=browser_group,
+    )
+    client = cast(_FactoryClient, self)
+    group._browser = self if browser_profile is None else cast(Any, type(self))(
+      browser=browser_profile,
+      remote=browser_remote,
+      key=client._key,
+      _command_sender=getattr(self, "_command_sender", None),
+    )
+    return group
 
-    def tab_from_target(self, data: dict, target) -> Tab:
-        """Build a Tab, tagging it with *target* in multi-browser mode (``None`` = local)."""
-        return self.tab_from(
-            data,
-            browser_profile=target.profile if target else None,
-            browser_name=target.display_name if target else None,
-            browser_remote=target.remote if target else None,
-        )
+  def tab_from_target(self, data: dict, target) -> Tab:
+    """Build a Tab, tagging it with *target* in multi-browser mode (``None`` = local)."""
+    return self.tab_from(
+      data,
+      browser_profile=target.profile if target else None,
+      browser_name=target.display_name if target else None,
+      browser_remote=target.remote if target else None,
+      browser_type=getattr(target, "browser_name", None) if target else None,
+      browser_group=_target_group(target),
+    )
 
-    def group_from_target(self, data: dict, target) -> Group:
-        """Build a Group, tagging it with *target* in multi-browser mode (``None`` = local)."""
-        return self.group_from(
-            data,
-            browser_profile=target.profile if target else None,
-            browser_name=target.display_name if target else None,
-            browser_remote=target.remote if target else None,
-        )
+  def group_from_target(self, data: dict, target) -> Group:
+    """Build a Group, tagging it with *target* in multi-browser mode (``None`` = local)."""
+    return self.group_from(
+      data,
+      browser_profile=target.profile if target else None,
+      browser_name=target.display_name if target else None,
+      browser_remote=target.remote if target else None,
+      browser_type=getattr(target, "browser_name", None) if target else None,
+      browser_group=_target_group(target),
+    )
 
-    @staticmethod
-    def tag_browser(item: dict, target) -> dict:
-        """Return *item* as-is locally, or with a ``browser`` key in multi-browser mode."""
-        return item if target is None else {**item, "browser": target.display_name}
+  @staticmethod
+  def tag_browser(item: dict, target) -> dict:
+    """Return *item* as-is locally, or with browser metadata in multi-browser mode."""
+    if target is None:
+      return item
+    return {**item, "browser": target.display_name, "browserGroup": _target_group(target)}

browser_cli/sdk/routing.py

@@ -37,6 +37,20 @@ _UNSET = object()
 def _browser_cli_package():
   return sys.modules.get("browser_cli") or importlib.import_module("browser_cli")
 
+def _with_profile_display(targets: list[BrowserTarget]) -> list[BrowserTarget]:
+  """Use profile-only labels when a command is already scoped to one remote."""
+  return [
+    BrowserTarget(
+      profile=target.profile,
+      display_name=target.profile if target.remote else target.display_name,
+      socket_path=target.socket_path,
+      remote=target.remote,
+      browser_name=target.browser_name,
+      display_group=None,
+    )
+    for target in targets
+  ]
+
 class RoutingMixin:
   """Fan-out + aggregation across active browsers, mixed into ``BrowserCLI``.
 
@@ -51,10 +65,15 @@ class RoutingMixin:
   def _multi_browser_targets(self) -> list[BrowserTarget]:
     client = self._client
     package = _browser_cli_package()
-    if client._browser is not None:
+    if client._browser is not None and not client._remote:
+      targets = package.remote_targets_for_alias(client._browser, key=client._key)
+      if len(targets) <= 1:
+        return []
+      targets = _with_profile_display(targets)
+    elif client._browser is not None:
       return []
-    if client._remote:
-      targets = package.remote_browser_targets(client._remote, key=client._key)
+    elif client._remote:
+      targets = _with_profile_display(package.remote_browser_targets(client._remote, key=client._key))
     else:
       targets = package.active_browser_targets()
     if len(targets) <= 1 and not any(target.remote for target in targets):
@@ -107,7 +126,12 @@ class RoutingMixin:
     if not multi_results:
       return self._client.dispatch(command, args or {})
     by_browser = {target.display_name: int(count or 0) for target, count in multi_results}
-    return BrowserCounts(total=sum(by_browser.values()), by_browser=by_browser)
+    browser_groups = {
+      target.display_name: target.display_group or "local"
+      for target, _count in multi_results
+      if target.display_group or target.remote is None
+    }
+    return BrowserCounts(total=sum(by_browser.values()), by_browser=by_browser, browser_groups=browser_groups)
 
   def multi_list(self, command: str, args: dict | None, mapper):
     """List command, flattening per-browser results in multi-browser mode.

browser_cli/serve/control.py

@@ -16,11 +16,19 @@ class ServeControlMixin:
 
   async def handle_control_command(self, msg: dict) -> bool:
     if self.command == "browser-cli.targets":
-      from browser_cli.client import active_browser_targets
-      targets = [
-        {"profile": target.profile, "displayName": target.display_name}
-        for target in active_browser_targets(include_remotes=False)
-      ]
+      from browser_cli.client import active_browser_targets, send_command
+      targets = []
+      for target in active_browser_targets(include_remotes=False):
+        item = {"profile": target.profile, "displayName": target.display_name}
+        try:
+          clients = send_command("clients.list", profile=target.profile, suppress_pq_warning=True)
+          if clients:
+            browser_name = clients[0].get("name")
+            if browser_name:
+              item["browserName"] = browser_name
+        except Exception:
+          pass
+        targets.append(item)
       await self.send_ok(targets, self.command)
       log_request(self.addr, self.command, None, "OK")
       return True

extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "browser-cli",
-  "version": "0.15.4",
+  "version": "0.15.6",
   "description": "Control your browser from the terminal or Python SDK",
   "browser_specific_settings": {
     "gecko": {

justfile

@@ -74,6 +74,18 @@ version-check:
      ext=$(grep -m1 '"version"' extension/manifest.json | cut -d'"' -f4); \
      if [ "$py" = "$ext" ]; then echo "ok: $py"; else echo "MISMATCH pyproject=$py manifest=$ext"; exit 1; fi
 
+# Build into /tmp/dist-browser-cli and publish using credentials from .env
+publish:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    set -a
+    [ ! -f .env ] || source .env
+    set +a
+    rm -rf /tmp/dist-browser-cli
+    mkdir -p /tmp/dist-browser-cli
+    uv build --out-dir /tmp/dist-browser-cli
+    uv publish /tmp/dist-browser-cli/*
+
 # ── Demos ──────────────────────────────────────────────────────────────
 
 # Run the Python SDK demo

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "real-browser-cli"
-version = "0.15.4"
+version = "0.15.6"
 description = "Control your real running browser from the terminal or Python SDK"
 readme = "README.md"
 license = { file = "LICENSE" }

tests/test_api.py

@@ -470,7 +470,7 @@ class TestTabs:
       tabs = b.tabs.list()
       tabs[0].close()
 
-    assert [tab.browser for tab in tabs] == ["host:work"]
+    assert [tab.browser for tab in tabs] == ["work"]
     assert mock_send.call_args_list == [
       call("tabs.list", {}, profile="work", remote="host:8765", key=None),
       call("tabs.close", {"tabId": 10}, profile="work", remote="host:8765", key=None),
@@ -491,6 +491,28 @@ class TestTabs:
       call("tabs.close", {"tabId": 10}, profile="work", remote="browser-host.example", key="agent"),
     ]
 
+  def test_tabs_list_browser_host_alias_fans_out_to_remote_targets(self, mock_send):
+    b = BrowserCLI(browser="browser-host.example", key="agent")
+    with patch(
+      "browser_cli.remote_targets_for_alias",
+      return_value=[
+        BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", browser_name="Chrome"),
+        BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", browser_name="Firefox"),
+      ],
+    ):
+      mock_send.side_effect = [[TAB_DATA], [{**TAB_DATA, "id": 11}], None]
+      tabs = b.tabs.list()
+      tabs[1].close()
+
+    assert [tab.browser for tab in tabs] == ["main", "work"]
+    assert [tab.browser_name for tab in tabs] == ["Chrome", "Firefox"]
+    assert [tab.browser_group for tab in tabs] == [None, None]
+    assert mock_send.call_args_list == [
+      call("tabs.list", {}, profile="main", remote="browser-host.example:8765", key="agent"),
+      call("tabs.list", {}, profile="work", remote="browser-host.example:8765", key="agent"),
+      call("tabs.close", {"tabId": 11}, profile="work", remote="browser-host.example:8765", key="agent"),
+    ]
+
   def test_tabs_active_returns_active_tab(self, b, mock_send):
     mock_send.side_effect = [[TAB_DATA], TAB_DATA]
 
@@ -537,12 +559,37 @@ class TestTabs:
       mock_send.side_effect = [3, 4]
       result = b.tabs.count("github")
 
-    assert result == BrowserCounts(total=7, by_browser={"uuid-1": 3, "work": 4})
+    assert result == BrowserCounts(
+      total=7,
+      by_browser={"uuid-1": 3, "work": 4},
+      browser_groups={"uuid-1": "local", "work": "local"},
+    )
     assert mock_send.call_args_list == [
       call("tabs.count", {"pattern": "github"}, profile="default"),
       call("tabs.count", {"pattern": "github"}, profile="work"),
     ]
 
+  def test_tabs_count_multi_browser_keeps_remote_display_groups(self, b, mock_send):
+    with patch(
+      "browser_cli.active_browser_targets",
+      return_value=[
+        BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+        BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+      ],
+    ):
+      mock_send.side_effect = [1, 2]
+      result = b.tabs.count()
+
+    assert result == BrowserCounts(
+      total=3,
+      by_browser={"browser-host.example:main": 1, "browser-host.example:work": 2},
+      browser_groups={"browser-host.example:main": "browser-host.example", "browser-host.example:work": "browser-host.example"},
+    )
+    assert mock_send.call_args_list == [
+      call("tabs.count", {"pattern": None}, profile="main", remote="browser-host.example:8765", key=None),
+      call("tabs.count", {"pattern": None}, profile="work", remote="browser-host.example:8765", key=None),
+    ]
+
   def test_tabs_query(self, b, mock_send):
     mock_send.return_value = [TAB_DATA]
     result = b.tabs.query("example")
@@ -659,7 +706,7 @@ class TestGroups:
       groups = b.groups.list()
       groups[0].close()
 
-    assert [group.browser for group in groups] == ["host:work"]
+    assert [group.browser for group in groups] == ["work"]
     assert mock_send.call_args_list == [
       call("group.list", {}, profile="work", remote="host:8765", key=None),
       call("group.close", {"groupId": 42}, profile="work", remote="host:8765", key=None),
@@ -691,7 +738,11 @@ class TestGroups:
       mock_send.side_effect = [2, 5]
       result = b.groups.count()
 
-    assert result == BrowserCounts(total=7, by_browser={"uuid-1": 2, "work": 5})
+    assert result == BrowserCounts(
+      total=7,
+      by_browser={"uuid-1": 2, "work": 5},
+      browser_groups={"uuid-1": "local", "work": "local"},
+    )
 
   def test_group_query(self, b, mock_send):
     mock_send.return_value = [GROUP_DATA]
@@ -750,8 +801,8 @@ class TestWindows:
       result = b.windows.list()
 
     assert result == [
-      {"id": 1, "tabCount": 2, "state": "normal", "browser": "uuid-1"},
-      {"id": 2, "tabCount": 3, "state": "maximized", "browser": "work"},
+      {"id": 1, "tabCount": 2, "state": "normal", "browser": "uuid-1", "browserGroup": "local"},
+      {"id": 2, "tabCount": 3, "state": "maximized", "browser": "work", "browserGroup": "local"},
     ]
 
   def test_windows_open_without_url(self, b, mock_send):
@@ -885,8 +936,8 @@ class TestSession:
       result = b.session.list()
 
     assert result == [
-      {"name": "first", "tabs": 2, "savedAt": 1712707200000, "browser": "uuid-1"},
-      {"name": "second", "tabs": 5, "savedAt": 1712707300000, "browser": "work"},
+      {"name": "first", "tabs": 2, "savedAt": 1712707200000, "browser": "uuid-1", "browserGroup": "local"},
+      {"name": "second", "tabs": 5, "savedAt": 1712707300000, "browser": "work", "browserGroup": "local"},
     ]
     assert mock_send.call_args_list == [
       call("session.list", {}, profile="default"),

tests/test_cli.py

@@ -4,7 +4,7 @@ import os
 import sys
 
 from click.testing import CliRunner
-from unittest.mock import patch
+from unittest.mock import call, patch
 
 from browser_cli.cli import main, _project_version
 from browser_cli.client import BrowserTarget
@@ -217,7 +217,13 @@ def test_clients_without_remote_shows_saved_remotes_without_pq_warning(tmp_path)
 
   registry_path = tmp_path / "registry.json"
   registry_path.write_text('{"main": "/tmp/.browser_cli/main.sock"}', encoding="utf-8")
-  remote_target = BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765")
+  remote_target = BrowserTarget(
+    "work",
+    "browser-host.example:work",
+    "",
+    remote="browser-host.example:8765",
+    display_group="browser-host.example",
+  )
 
   def fake_send_command(command, args=None, profile=None, remote=None, key=None, suppress_pq_warning=False):
     assert command == "clients.list"
@@ -239,7 +245,11 @@ def test_clients_without_remote_shows_saved_remotes_without_pq_warning(tmp_path)
 
   assert result.exit_code == 0
   active_targets.assert_called_once_with(suppress_pq_warning=True)
+  assert "local" in result.output
   assert "Chrome" in result.output
+  assert "browser-host.example" in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "work" in result.output
   assert "Remote Chrome" in result.output
   assert "post-quantum" not in result.output
 
@@ -362,9 +372,33 @@ def test_tabs_list_multi_browser_shows_browser_column():
 
   assert result.exit_code == 0
   assert "Browser" in result.output
+  assert "local" in result.output
   assert "550e8400-e29b-41d4-a716-446655440000" in result.output
   assert "work" in result.output
 
+def test_tabs_list_unscoped_groups_remote_targets_by_host():
+  targets = [
+    BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+    BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+  ]
+
+  def fake_send_command(command, args=None, profile=None, remote=None, key=None):
+    assert command == "tabs.list"
+    assert remote == "browser-host.example:8765"
+    return [{"id": 1, "windowId": 1, "active": True, "title": profile, "url": "https://example.com"}]
+
+  with patch("browser_cli.active_browser_targets", return_value=targets), patch(
+    "browser_cli.send_command", side_effect=fake_send_command
+  ):
+    result = CliRunner().invoke(main, ["tabs", "list"])
+
+  assert result.exit_code == 0
+  assert "browser-host.example" in result.output
+  assert "browser-host.example:main" not in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "main" in result.output
+  assert "work" in result.output
+
 def test_tabs_list_with_remote_uses_only_remote_targets():
   with patch(
     "browser_cli.active_browser_targets",
@@ -379,7 +413,8 @@ def test_tabs_list_with_remote_uses_only_remote_targets():
     result = CliRunner().invoke(main, ["--remote", "remote-host:8765", "tabs", "list"])
 
   assert result.exit_code == 0
-  assert "remote-host:work" in result.output
+  assert "work" in result.output
+  assert "remote-host:work" not in result.output
   assert "Remote" in result.output
   send_command.assert_called_once_with("tabs.list", {}, profile="work", remote="remote-host:8765", key=None)
 
@@ -400,6 +435,81 @@ def test_tabs_list_with_explicit_browser_does_not_show_browser_column():
   assert "Browser" not in result.output
   send_command.assert_called_once_with("tabs.list", {}, profile="work", remote=None, key=None)
 
+def test_tabs_tree_with_browser_host_alias_fans_out_to_remote_targets():
+  targets = [
+    BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", browser_name="Chrome"),
+    BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", browser_name="Firefox"),
+  ]
+
+  def fake_send_command(command, args=None, profile=None, remote=None, key=None):
+    assert remote == "browser-host.example:8765"
+    if command == "tabs.list":
+      return [{
+        "id": 1 if profile == "main" else 2,
+        "windowId": 1,
+        "active": True,
+        "index": 0,
+        "title": f"{profile} tab",
+        "url": "https://example.com",
+      }]
+    if command == "group.list":
+      return []
+    raise AssertionError(command)
+
+  with patch("browser_cli.remote_targets_for_alias", return_value=targets), patch(
+    "browser_cli.send_command", side_effect=fake_send_command
+  ) as send_command:
+    result = CliRunner().invoke(main, ["--browser", "browser-host.example", "tabs", "tree"])
+
+  assert result.exit_code == 0
+  assert "main" in result.output
+  assert "work" in result.output
+  assert "browser-host.example:main" not in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "main tab" in result.output
+  assert "work tab" in result.output
+  assert send_command.call_args_list == [
+    call("tabs.list", {}, profile="main", remote="browser-host.example:8765", key=None),
+    call("tabs.list", {}, profile="work", remote="browser-host.example:8765", key=None),
+    call("group.list", {}, profile="main", remote="browser-host.example:8765", key=None),
+    call("group.list", {}, profile="work", remote="browser-host.example:8765", key=None),
+  ]
+
+def test_tabs_tree_unscoped_groups_remote_targets_by_host():
+  targets = [
+    BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+    BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+  ]
+
+  def fake_send_command(command, args=None, profile=None, remote=None, key=None):
+    assert remote == "browser-host.example:8765"
+    if command == "tabs.list":
+      return [{
+        "id": 1 if profile == "main" else 2,
+        "windowId": 1,
+        "active": True,
+        "index": 0,
+        "title": f"{profile} tab",
+        "url": "https://example.com",
+      }]
+    if command == "group.list":
+      return []
+    raise AssertionError(command)
+
+  with patch("browser_cli.active_browser_targets", return_value=targets), patch(
+    "browser_cli.send_command", side_effect=fake_send_command
+  ):
+    result = CliRunner().invoke(main, ["tabs", "tree"])
+
+  assert result.exit_code == 0
+  assert "browser-host.example" in result.output
+  assert "main" in result.output
+  assert "work" in result.output
+  assert "browser-host.example:main" not in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "main tab" in result.output
+  assert "work tab" in result.output
+
 def test_tabs_count_multi_browser_shows_total():
   counts = {"default": 3, "work": 4}
 
@@ -419,9 +529,36 @@ def test_tabs_count_multi_browser_shows_total():
 
   assert result.exit_code == 0
   assert "Browser" in result.output
+  assert "local" in result.output
   assert "Total" in result.output
   assert "7" in result.output
 
+def test_tabs_count_unscoped_groups_remote_targets_by_host():
+  counts = {"main": 1, "work": 2}
+
+  def fake_send_command(command, args=None, profile=None, remote=None, key=None):
+    assert command == "tabs.count"
+    assert remote == "browser-host.example:8765"
+    return counts[profile]
+
+  with patch(
+    "browser_cli.active_browser_targets",
+    return_value=[
+      BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+      BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+    ],
+  ), patch("browser_cli.send_command", side_effect=fake_send_command):
+    result = CliRunner().invoke(main, ["tabs", "count"])
+
+  assert result.exit_code == 0
+  assert "browser-host.example" in result.output
+  assert "browser-host.example:main" not in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "main" in result.output
+  assert "work" in result.output
+  assert "Total" in result.output
+  assert "3" in result.output
+
 def test_group_count_multi_browser_shows_total():
   counts = {"default": 1, "work": 2}
 
@@ -443,6 +580,29 @@ def test_group_count_multi_browser_shows_total():
   assert "Total" in result.output
   assert "3" in result.output
 
+def test_groups_list_unscoped_groups_remote_targets_by_host():
+  targets = [
+    BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+    BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+  ]
+
+  def fake_send_command(command, args=None, profile=None, remote=None, key=None):
+    assert command == "group.list"
+    assert remote == "browser-host.example:8765"
+    return [{"id": 1, "title": profile, "color": "blue", "collapsed": False, "tabCount": 2}]
+
+  with patch("browser_cli.active_browser_targets", return_value=targets), patch(
+    "browser_cli.send_command", side_effect=fake_send_command
+  ):
+    result = CliRunner().invoke(main, ["groups", "list"])
+
+  assert result.exit_code == 0
+  assert "browser-host.example" in result.output
+  assert "browser-host.example:main" not in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "main" in result.output
+  assert "work" in result.output
+
 def test_group_list_leaves_unnamed_group_cell_empty():
   with patch(
     "browser_cli.send_command",
@@ -491,10 +651,34 @@ def test_windows_list_multi_browser_shows_browser_column():
 
   assert result.exit_code == 0
   assert "Browser" in result.output
+  assert "local" in result.output
   assert "Focused" not in result.output
   assert "uuid-1" in result.output
   assert "work" in result.output
 
+def test_windows_list_unscoped_groups_remote_targets_by_host():
+  targets = [
+    BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+    BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+  ]
+
+  def fake_send_command(command, args=None, profile=None, remote=None, key=None):
+    assert command == "windows.list"
+    assert remote == "browser-host.example:8765"
+    return [{"id": 1, "alias": profile, "focused": True, "tabCount": 2, "state": "normal"}]
+
+  with patch("browser_cli.active_browser_targets", return_value=targets), patch(
+    "browser_cli.send_command", side_effect=fake_send_command
+  ):
+    result = CliRunner().invoke(main, ["windows", "list"])
+
+  assert result.exit_code == 0
+  assert "browser-host.example" in result.output
+  assert "browser-host.example:main" not in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "main" in result.output
+  assert "work" in result.output
+
 def test_session_list_multi_browser_shows_browser_column():
   def fake_send_command(command, args=None, profile=None):
     assert command == "session.list"
@@ -511,11 +695,37 @@ def test_session_list_multi_browser_shows_browser_column():
 
   assert result.exit_code == 0
   assert "Browser" in result.output
+  assert "local" in result.output
   assert "uuid-1" in result.output
   assert "work" in result.output
   assert "default-session" in result.output
   assert "work-session" in result.output
 
+def test_session_list_unscoped_groups_remote_targets_by_host():
+  targets = [
+    BrowserTarget("main", "browser-host.example:main", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+    BrowserTarget("work", "browser-host.example:work", "", remote="browser-host.example:8765", display_group="browser-host.example"),
+  ]
+
+  def fake_send_command(command, args=None, profile=None, remote=None, key=None):
+    assert command == "session.list"
+    assert remote == "browser-host.example:8765"
+    return [{"name": f"{profile}-session", "tabs": 2, "savedAt": 1712707200000}]
+
+  with patch("browser_cli.active_browser_targets", return_value=targets), patch(
+    "browser_cli.send_command", side_effect=fake_send_command
+  ):
+    result = CliRunner().invoke(main, ["session", "list"])
+
+  assert result.exit_code == 0
+  assert "browser-host.example" in result.output
+  assert "browser-host.example:main" not in result.output
+  assert "browser-host.example:work" not in result.output
+  assert "main" in result.output
+  assert "work" in result.output
+  assert "main-session" in result.output
+  assert "work-session" in result.output
+
 def test_session_list_with_explicit_browser_does_not_show_browser_column():
   with patch(
     "browser_cli.active_browser_targets",

tests/test_client.py

@@ -342,7 +342,7 @@ def test_active_browser_targets_includes_remote_targets(monkeypatch, tmp_path):
     def fake_send_command(command, args=None, profile=None, remote=None, key=None):
         assert command == "browser-cli.targets"
         assert remote == endpoint
-        return [{"profile": "work", "displayName": "work"}]
+        return [{"profile": "work", "displayName": "work", "browserName": "Firefox"}]
 
     monkeypatch.setattr("browser_cli.client.core.send_command", fake_send_command)
 
@@ -352,6 +352,8 @@ def test_active_browser_targets_includes_remote_targets(monkeypatch, tmp_path):
     assert targets[0].profile == "work"
     assert targets[0].display_name == "browser-host.example:work"
     assert targets[0].remote == endpoint
+    assert targets[0].browser_name == "Firefox"
+    assert targets[0].display_group == "browser-host.example"
 
 def test_looks_like_domain():
     assert _looks_like_domain("browsercli.yiprawr.dev") is True

tests/test_rendering.py

@@ -5,15 +5,26 @@ from rich.tree import Tree
 
 from browser_cli.models import Tab
 from browser_cli.commands import rendering
+from browser_cli.commands.rendering import common
 
 def test_shorten_uses_ellipsis():
   assert rendering.shorten("abcdef", 4) == "abc…"
   assert rendering.shorten("abc", 4) == "abc"
 
 def test_terminal_width_prefers_shell_width_when_rich_is_redirected(monkeypatch):
-  monkeypatch.setattr(rendering.shutil, "get_terminal_size", lambda fallback: terminal_size((140, 20)))
+  monkeypatch.setattr(common.shutil, "get_terminal_size", lambda fallback: terminal_size((140, 20)))
   assert rendering.terminal_width(Console(width=80)) == 140
 
+def test_browser_label_style_distinguishes_browser_families():
+  assert rendering.browser_label_style("Firefox") == "orange1"
+  assert rendering.browser_label_style("Chrome") == "cyan"
+  assert rendering.browser_label_style(None) == "bold cyan"
+
+def test_scoped_browser_label_strips_repeated_remote_prefix():
+  assert rendering.scoped_browser_label("browser-host.example:work", "browser-host.example", grouped=True) == "work"
+  assert rendering.scoped_browser_label("work", "browser-host.example", grouped=True) == "work"
+  assert rendering.scoped_browser_label("browser-host.example:work", "browser-host.example", grouped=False) == "browser-host.example:work"
+
 def test_tab_tree_label_is_reusable_no_wrap_text():
   tab = type("Tab", (), {"id": 1, "title": "abcdef", "active": True, "url": "https://example.com"})()
   label = rendering.tab_tree_label(tab, title_limit=4, show_urls=True, url_limit=12)
@@ -29,8 +40,8 @@ def test_print_tree_uses_detected_width(monkeypatch):
       widths.append(kwargs.get("width"))
       super().__init__(*args, **kwargs)
 
-  monkeypatch.setattr(rendering, "Console", CapturingConsole)
-  monkeypatch.setattr(rendering, "terminal_width", lambda console=None: 132)
+  monkeypatch.setattr(common, "Console", CapturingConsole)
+  monkeypatch.setattr(common, "terminal_width", lambda console=None: 132)
   rendering.print_tree(Tree("Root"))
   assert widths == [132]
 
@@ -48,6 +59,21 @@ def test_build_tabs_tree_groups_by_browser_window_and_group():
   assert "collapsed" in text
   assert "Inside" in text
 
+def test_build_tabs_tree_groups_remote_browsers_by_scope():
+  tabs = [
+    Tab(id=1, window_id=5, active=False, muted=False, title="Remote A", url="https://example.com/a", index=0, browser="main", browser_group="browser-host.example"),
+    Tab(id=2, window_id=6, active=False, muted=False, title="Remote B", url="https://example.com/b", index=0, browser="work", browser_group="browser-host.example"),
+    Tab(id=3, window_id=7, active=False, muted=False, title="Local", url="https://example.com/local", index=0, browser="local"),
+  ]
+  tree = rendering.build_tabs_tree(tabs, [], console=Console(width=120))
+  text = "\n".join(str(line) for line in tree.__rich_console__(Console(width=120), Console(width=120).options))
+  assert "browser-host.example" in text
+  assert "main" in text
+  assert "work" in text
+  assert "browser-host.example:main" not in text
+  assert "browser-host.example:work" not in text
+  assert "Local" in text
+
 def test_build_windows_tree_keeps_multi_browser_windows_separate():
   tabs = [
     Tab(id=1, window_id=5, active=False, muted=False, title="Work Tab", url="https://example.com/work", index=0, browser="work"),

uv.lock

@@ -465,7 +465,7 @@ wheels = [
 
 [[package]]
 name = "real-browser-cli"
-version = "0.15.4"
+version = "0.15.6"
 source = { editable = "." }
 dependencies = [
     { name = "click" },