cli-tool-browser-expert

<agent_routing> When this skill is invoked by a parent Codex or Claude session and the current agent is not cli-tool-expert, delegate the work to cli-tool-expert instead of performing CLI browser lifecycle work inline. Pass the complete user request, relevant file paths, constraints, and required validation.

When the current agent is cli-tool-expert, follow this skill normally. </agent_routing>

<quick_start> Route based on intent:

Intent	Route
Add browser support to existing CLI	Follow <essential_principles> below, starting from the scaffold at _repo/skills/cli-tool/templates/browser/{{name_underscore}}_cli/browser.py
Create new browser CLI from scratch	Use the cli-tool skill with --type browser
Fix browser auth issues	Check ## Known Issues below first, then read _repo/cli-tools-shared/cli_tools_shared/auth.py (BrowserAutomation) and auth_verifier.py (AuthVerifier)
Understand the architecture	Read _repo/cli-tools-shared/cli_tools_shared/auth.py and auth_verifier.py directly — their docstrings are the source of truth
</quick_start>

<essential_principles>

from cli_tools_shared.auth import BrowserAutomation
from .config import get_config

class MyBrowser(BrowserAutomation):
    SESSION_NAME = "myservice"
    LOGIN_URL = "https://myservice.com/login"
    AUTH_CHECK_URL = "https://myservice.com/dashboard"
    AUTH_URL_PATTERN = r"/login|/register"
    AUTH_SUCCESS_SELECTOR = 'selector-visible-when-logged-in'

    def __init__(self, config=None):
        config = config or get_config()
        super().__init__(config)

If browser.py has custom methods beyond __init__, something is wrong.

• def is_logged_in / def is_authenticated / def check_auth
• def _ensure_logged_in / def verify_session / def check_session
• def _check_browser_status / def check_browser_session
• Direct sync_playwright() or async_playwright() imports
• Direct launch_persistent_context calls
• Custom BrowserService classes (legacy pattern)

~/.local/share/cli-tools/_shared/chromium-profile

Resolved by BaseConfig.get_persistent_profile_dir() / uses_shared_chromium_profile(). New browser CLIs need zero per-CLI glue — the shared package owns the path.

Stay isolated when:

• the active auth profile name is not default (multi-account tools), or
• CLI_TOOLS_ISOLATE_CHROME_PROFILE=1, or
• the config does not declare CredentialType.BROWSER_SESSION.