Merge pull request #68 from sanketsudake/helium-default-browser

Make Helium the browser these configs drive

Author: sanketsudake

CLAUDE.md

@@ -163,8 +163,10 @@ Rules and docs reference scripts via `$CLAUDE_CONFIG_DIR/scripts/...` so the pat
 `claude/scripts/` currently holds `agent-routing-hook.sh` (the `PreToolUse` routing hook referenced by `rules/model-routing.md`),
 `safety-guard-hook.py` (a `PreToolUse` deny/ask gate on `Bash` and `Edit|Write` — the Claude-side twin of pi's `permission-gate.ts` + `protected-paths.ts`, referenced by `rules/git-hygiene.md`),
 `usage-log-hook.py` + `usage-report.py` (`SubagentStop`/`Stop`/`SessionEnd` telemetry into `$CLAUDE_CONFIG_DIR/usage.jsonl` and its aggregator, also referenced by `rules/model-routing.md`; `make usage-report` runs the aggregator for every profile),
+`browser-endpoint.sh` (prints the CDP endpoint of the user's browser, referenced by `claude/CLAUDE.md`),
 and `statusline-command.sh` (a `statusLine` hook script).
-None is symlinked-by-reference; a profile must opt in via its own `settings.json`, which is not tracked in this repo — each hook script's header carries its wiring snippet.
+No hook among them is wired by default; a profile must opt in via its own `settings.json`, which is not tracked in this repo — each hook script's header carries its wiring snippet.
+`browser-endpoint.sh` is a plain helper instead: it is invoked by path and needs no wiring.
 Agents are single `.md` files fetched and tracked by `resource-manager.sh` (see "Skill & agent source management").
 - **`plugins.txt` is desired-state only.**
   Installation is manual per-profile; the Makefile only reports drift.

claude/CLAUDE.md

@@ -36,17 +36,13 @@ It preserves rendered output, code blocks, tables, and frontmatter.
 
 # Interacting with browser
 
-- Default to `/agent-browser` for browser work.
-For my running Chrome (live logins), attach with `--cdp 9222 --pin-tab`;
-that needs Chrome launched with `--remote-debugging-port=9222` (`open -a "Google Chrome" --args --remote-debugging-port=9222`, no consent prompt).
-The `chrome://inspect` toggle serves no `/json` discovery, so `--cdp 9222` and `--auto-connect` time out there;
-pass the browser WebSocket URL from Chrome's `DevToolsActivePort` file to `--cdp` instead.
-For a detached or headless browser, use its own named session.
-- Use `/drive-chrome-cdp` (`chrome-cdp`) when a skill names it (the Workday, Engage, and Microsoft-SSO skills)
-or when the task needs its primitives:
-`wait --request`, cascade `select`, `fill --by cell`, `--in-row`, `grid`, `recipe`, exit-code branching.
-On the `chrome://inspect` path, `--endpoint ws://…` (the URL from `DevToolsActivePort`) attaches where port discovery fails.
-For parallel agents on one Chrome, `--session <name>` namespaces the sticky current tab so they do not steal each other's tab.
-- Both tools attach to my real Chrome and can raise one "Allow remote debugging?" consent prompt;
-run one probe and wait for it, do not stack probes.
-- Type no credentials in either tool; stop at a login or passkey page and ask me to sign in.
+- My browser is **Helium**, not Chrome; it holds the live logins.
+Read "the user's real Chrome" in any skill as Helium.
+- Attach to the running browser; never launch a new one.
+`$CLAUDE_CONFIG_DIR/scripts/browser-endpoint.sh` prints the CDP endpoint to pass explicitly —
+port-only attach times out.
+If the script fails, ask me to enable `helium://inspect/#remote-debugging`.
+- Default to `/agent-browser`; use `/drive-chrome-cdp` when a skill names it or needs its primitives.
+- Attaching raises one consent prompt per session:
+start the `chrome-cdp` daemon, run one probe, and wait — do not stack probes.
+- Type no credentials; stop at a login or passkey page and ask me to sign in.

claude/scripts/browser-endpoint.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Print the CDP browser WebSocket endpoint of the user's browser (Helium).
+#
+# Helium is a Chromium fork; its remote-debugging port file is its own, not
+# Chrome's, so tools that default to Chrome's path fail with connection_failed.
+# The port file appears only after the user enables the toggle at
+# helium://inspect/#remote-debugging (no restart; tabs and logins survive).
+# That toggle serves no /json discovery, so port-only attach (--cdp 9222,
+# --auto-connect) times out; pass this endpoint explicitly instead.
+#
+# Usage:
+#   EP="$("$CLAUDE_CONFIG_DIR"/scripts/browser-endpoint.sh)" || ask the user to enable the toggle
+#   chrome-cdp daemon start --endpoint "$EP" --json
+#   agent-browser --cdp "$EP" --pin-tab
+#
+# Exit 1 with a message on stderr when the port file is absent.
+set -euo pipefail
+
+PORT_FILE="${HELIUM_DEVTOOLS_PORT_FILE:-$HOME/Library/Application Support/net.imput.helium/DevToolsActivePort}"
+
+if [ ! -s "$PORT_FILE" ]; then
+  echo "browser-endpoint: no port file at $PORT_FILE" >&2
+  echo "browser-endpoint: ask the user to enable helium://inspect/#remote-debugging" >&2
+  exit 1
+fi
+
+port="$(head -1 "$PORT_FILE")"
+path="$(sed -n 2p "$PORT_FILE")"
+echo "ws://127.0.0.1:${port}${path}"

skills/README.md

@@ -91,7 +91,7 @@ Generated by `make skills-catalog` — do not edit by hand (`make skills-doctor`
 | [`drive-chrome-cdp`](https://github.com/sanketsudake/chrome-cdp-cli/tree/deee3056260e6dea5f182760e3559d79a7222291/skills/drive-chrome-cdp) | Drive the user's real, already-running local Chrome — its live tabs, logins, and cookies, so it types no credentials — from the shell via the `chrome-cdp` CL... |
 | [`fill-workday-timesheet`](fill-workday-timesheet/SKILL.md) | Fills in the user's Workday timesheet: hours per weekday against a project for one week or every unfilled week up to a date, review-first, showing the planne... |
 | [`list-week-meetings`](list-week-meetings/SKILL.md) | Lists a week's meetings from the Outlook (Microsoft 365) web calendar, grouped by day with time, title, organizer, online/in-person status, and meeting status. |
-| [`login-microsoft-sso`](login-microsoft-sso/SKILL.md) | Ensures a Chrome tab is signed in to an app behind your organization's Microsoft (Entra) SSO (e.g. Workday, Engage, Outlook), driven by the `chrome-cdp` CLI ... |
+| [`login-microsoft-sso`](login-microsoft-sso/SKILL.md) | Ensures a browser tab is signed in to an app behind your organization's Microsoft (Entra) SSO (e.g. Workday, Engage, Outlook), driven by the `chrome-cdp` CLI... |
 | [`record-engage-activity`](record-engage-activity/SKILL.md) | Fills and submits the Engage Add Activity form (category, type, date, quantity, notes) via the chrome-cdp CLI, showing the entry and points before submitting. |
 
 ## knowledge-base

skills/apply-workday-leave/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   reconciles the timesheet so the leave day carries no project hours.
   Use when the user wants to apply leave, absence, sick leave, casual leave,
   planned leave, or comp off in Workday, or invokes /apply-workday-leave.
-  Drives the user's real Chrome via the chrome-cdp CLI and logs in through
+  Drives the user's real browser via the chrome-cdp CLI and logs in through
   login-microsoft-sso.
 disable-model-invocation: true
 license: Apache-2.0
@@ -17,7 +17,7 @@ metadata:
 
 # Apply Workday Leave
 
-This skill automates the Workday **Request Absence** flow via **`chrome-cdp`** on the user's real, logged-in Chrome.
+This skill automates the Workday **Request Absence** flow via **`chrome-cdp`** on the user's real, logged-in browser.
 It requests absence for given dates and type, shows the plan, and waits for confirmation before submitting — then checks the timesheet and clears any project hours already entered.
 Submitting writes real data and notifies the approver; never submit without explicit confirmation.
 

skills/approve-workday-tasks/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   Use when the user wants to review or approve pending Workday tasks,
   invoked as /approve-workday-tasks, or mentions Workday "My Tasks",
   pending approvals, Time Entry Approval, or the chrome-cdp CLI.
-  Drives the user's real Chrome via chrome-cdp and logs in through
+  Drives the user's real browser via chrome-cdp and logs in through
   login-microsoft-sso.
 disable-model-invocation: true
 license: Apache-2.0
@@ -17,7 +17,7 @@ metadata:
 
 # Approve Workday Tasks
 
-Automates the Workday **My Tasks** approval flow with review first, using **`chrome-cdp`** on the user's real, logged-in Chrome.
+Automates the Workday **My Tasks** approval flow with review first, using **`chrome-cdp`** on the user's real, logged-in browser.
 It lists pending items and approves only the ones the user selects.
 Never approve an item the user did not explicitly choose.
 

skills/fill-workday-timesheet/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   Use when the user wants to fill in their Workday timesheet ("fill my
   timesheet", "make sure time is entered through the 15th"), invoked as
   /fill-workday-timesheet.
-  Drives the user's real Chrome via the chrome-cdp CLI, logging in through
+  Drives the user's real browser via the chrome-cdp CLI, logging in through
   login-microsoft-sso.
 disable-model-invocation: true
 license: Apache-2.0
@@ -19,7 +19,7 @@ metadata:
 
 # Fill Workday Timesheet
 
-Automates Workday's **Enter Time** flow with the **`chrome-cdp`** CLI, in the user's real, logged-in Chrome.
+Automates Workday's **Enter Time** flow with the **`chrome-cdp`** CLI, in the user's real, logged-in browser.
 For each week in scope, it proposes hours per weekday against a project, shows the whole plan, and waits for confirmation before saving.
 Entering time writes real data.
 

skills/list-week-meetings/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   meeting status.
   Use when the user asks for their week's meetings, "what's on my calendar
   this week", a meeting list, or invokes /list-week-meetings.
-  Drives the user's real, logged-in Chrome via the chrome-cdp CLI and logs
+  Drives the user's real, logged-in browser via the chrome-cdp CLI and logs
   in through login-microsoft-sso (app outlook).
   Read-only — never creates, edits, or deletes calendar events.
 disable-model-invocation: true
@@ -19,7 +19,7 @@ metadata:
 # List Week Meetings
 
 This skill reads a week's meetings from the Outlook web calendar.
-It uses the `chrome-cdp` CLI to drive the user's real, logged-in Chrome browser.
+It uses the `chrome-cdp` CLI to drive the user's real, logged-in browser.
 It groups events by day.
 It does not create, edit, or delete any event.
 

skills/login-microsoft-sso/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: login-microsoft-sso
 description: >-
-  Ensures a Chrome tab is signed in to an app behind your organization's
+  Ensures a browser tab is signed in to an app behind your organization's
   Microsoft (Entra) SSO (e.g. Workday, Engage, Outlook), driven by the
-  `chrome-cdp` CLI on the user's real, already-logged-in Chrome — so it
+  `chrome-cdp` CLI on the user's real, already-logged-in browser — so it
   types no credentials.
   Use when another skill or task needs a logged-in tab before automating
   Workday, Engage, or Outlook web, or when the user runs
@@ -19,8 +19,8 @@ metadata:
 
 # Login to an SSO app (Microsoft-federated)
 
-Ensure a Chrome tab is signed in to an app behind your organization's **Microsoft (Entra) SSO**.
-Use the **`chrome-cdp`** CLI on the user's real, already signed-in Chrome — this skill types **no** credentials.
+Ensure a browser tab is signed in to an app behind your organization's **Microsoft (Entra) SSO**.
+Use the **`chrome-cdp`** CLI on the user's real, already signed-in browser — this skill types **no** credentials.
 
 > See **`drive-chrome-cdp`** for CLI setup, output contract, and the passkey rule.
 > Local skill, maintained in this repo (`.source.json` has `"repo": null`).
@@ -44,8 +44,17 @@ All commands take `--json`.
 Parse the envelope and branch on the exit code (see `drive-chrome-cdp`).
 
 1. **Connection.**
-   Run `chrome-cdp doctor --json`.
-   If `ok:false` (connection_failed), tell the user to enable `chrome://inspect/#remote-debugging`, then re-run.
+   `doctor` defaults to Chrome's port file, and the user's browser is Helium —
+   so pass the endpoint and start the daemon first (one consent prompt per session):
+
+   ```sh
+   EP="$("$CLAUDE_CONFIG_DIR"/scripts/browser-endpoint.sh)"
+   chrome-cdp daemon start --endpoint "$EP" --json
+   ```
+
+   Then run `chrome-cdp doctor --json`.
+   If the script fails, or `ok:false` (connection_failed),
+   tell the user to enable `helium://inspect/#remote-debugging`, then re-run.
    Do not proceed until ready.
 2. **Pick a tab.**
    Run `chrome-cdp list --url "<app host>" --json` (filters, so it skips scanning the full list).
@@ -77,7 +86,7 @@ Parse the envelope and branch on the exit code (see `drive-chrome-cdp`).
 
 ## Output
 
-The Chrome tab id (from `list` or `use`), signed in to the app.
+The browser tab id (from `list` or `use`), signed in to the app.
 Reuse it via `--target <id>` (or the sticky `use`).
 
 ## Safety

skills/record-engage-activity/SKILL.md

@@ -22,7 +22,7 @@ metadata:
 
 # Record Engage Activity
 
-Assisted, review-first automation of the Engage **Add Activity** form, driven by the **`chrome-cdp`** CLI (the user's real, logged-in Chrome).
+Assisted, review-first automation of the Engage **Add Activity** form, driven by the **`chrome-cdp`** CLI (the user's real, logged-in browser).
 It fills category, type, date, quantity, and notes, then shows the entry and points before submitting.
 Submit only after the user confirms — it writes real data and points.