feat: XDG config discovery, extraArgs support, and WSL2/container fixes

[mjdaly]

⚠️ Dependencies

This PR depends on the following unmerged PRs being merged first:

• Multi-agent concurrency and external browser mode #24 - Multi-agent concurrency and external browser mode (creates config.ts)
• HTTP-only client with 99% memory reduction #25 - HTTP-only client with 99% memory reduction (creates client-lite.ts)

The files modified in this PR (config.ts, client-lite.test.ts) do not exist in upstream main yet.

---

Summary

This PR adds several configuration improvements for better cross-platform and container support:

1. XDG and Project-Level Config Discovery

• XDG Base Directory Specification support for config and state files
• Project-level config discovery (walks up directory tree looking for .dev-browser/config.json)
• DEV_BROWSER_CONFIG environment variable for explicit config path override
• Backward compatible with existing ~/.dev-browser/ setups

2. Browser Extra Arguments (browser.extraArgs)

• Pass custom command-line flags to Chrome via config
• Essential for WSL2/container environments where GPU causes crashes

3. Default User Data Directory for CDP

• Chrome requires a non-default profile for CDP debugging
• Now defaults to $XDG_STATE_HOME/dev-browser/chrome-profile
• Configurable via browser.userDataDir for using existing profiles

4. WSL2/Container SIGILL Fix Documentation

• Documents the GPU-related SIGILL crash in virtualized environments
• Provides recommended flags: --disable-gpu, --disable-software-rasterizer, --no-sandbox

---

Config Discovery Priority

Config file:

1. DEV_BROWSER_CONFIG environment variable
2. .dev-browser/config.json in cwd or ancestor directories (project config)
3. $XDG_CONFIG_HOME/dev-browser/config.json (XDG compliant)
4. ~/.config/dev-browser/config.json (XDG default)
5. ~/.dev-browser/config.json (legacy fallback)

State files (active-servers.json, chrome-profile):

1. $XDG_STATE_HOME/dev-browser/
2. ~/.local/state/dev-browser/
3. ~/.dev-browser/ (legacy)

---

New Config Options

{
  "browser": {
    "path": "/opt/google/chrome/google-chrome",
    "userDataDir": "/path/to/profile",
    "extraArgs": ["--disable-gpu", "--no-sandbox"]
  }
}

Option	Description
browser.userDataDir	Browser profile directory (defaults to XDG state dir)
browser.extraArgs	Extra Chrome flags (e.g., ["--disable-gpu"])

---

WSL2/Container Example

For environments with GPU virtualization issues:

{
  "browser": {
    "path": "/opt/google/chrome/google-chrome",
    "extraArgs": [
      "--disable-gpu",
      "--disable-software-rasterizer",
      "--disable-dev-shm-usage",
      "--no-sandbox"
    ]
  }
}

---

Test plan

• All existing tests pass
• TypeScript compiles without errors
• 77 tests passing (23 new config discovery tests)
• Tested extraArgs flow from config → shell → browser launch

Code changes

File	Change
src/config.ts	XDG paths, project config, extraArgs in interface
src/external-browser.ts	Default userDataDir, pass extraArgs to Chrome
scripts/get-browser-config.ts	Output BROWSER_EXTRA_ARGS
scripts/start-external-browser.ts	Parse and pass extraArgs
server.sh	Export EXTRA_ARGS env var
SKILL.md	Full documentation of new features

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d2156e8b48

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Try the configured end port in allocation loop

The portRange.end value is documented as the “last port to try,” but the loop uses port < end, so the end port is never checked. If the only free port is exactly end (or start === end), findAvailablePort will throw “No available ports” even though a valid port exists. Consider using <= end or clarifying that end is exclusive.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve viewport on page creation

The server no longer applies GetPageRequest.viewport when creating a new page. Existing callers (e.g., client.page(name, { viewport })) still send a viewport and expect it to be applied, but this handler now ignores it, so viewport sizing silently regresses. This breaks the documented API behavior for viewport on creation unless clients are updated to call the new set-viewport endpoint.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Pass CDP args when launching .app on macOS

When browserPath ends with .app, launchBrowserDetached calls open -a without --args, so neither --remote-debugging-port nor --user-data-dir is applied. That means cdpPort/userDataDir are ignored and the auto-launched browser won’t open the configured CDP port, causing getCdpEndpoint to time out on macOS when users follow the documented .app path configuration.

Useful? React with 👍 / 👎.