From b19b9cd152a0ab9ec802e320c79c2f810f9e51e6 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Tue, 25 Aug 2026 15:55:20 +0530 Subject: [PATCH 1/2] Make Helium the browser these configs drive MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The day-to-day browser with the live SSO logins is Helium, a Chromium fork, not Google Chrome. Chrome's DevToolsActivePort is stale, so the default attach path fails and launching Chrome opens an empty profile. - claude/CLAUDE.md: Helium-first browser section — the helium://inspect/#remote-debugging toggle, the DevToolsActivePort -> ws:// endpoint recipe, and daemon start --endpoint for one consent prompt per session. - login-microsoft-sso: attach through Helium's endpoint before doctor. - Workday/Engage/Outlook skills: "real Chrome" -> "real browser" so the prose no longer names the wrong application. --- claude/CLAUDE.md | 27 ++++++++++++++++++-------- skills/README.md | 2 +- skills/apply-workday-leave/SKILL.md | 4 ++-- skills/approve-workday-tasks/SKILL.md | 4 ++-- skills/fill-workday-timesheet/SKILL.md | 4 ++-- skills/list-week-meetings/SKILL.md | 4 ++-- skills/login-microsoft-sso/SKILL.md | 24 ++++++++++++++++------- skills/record-engage-activity/SKILL.md | 2 +- 8 files changed, 46 insertions(+), 25 deletions(-) diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md index 804c6a7..bd4beae 100644 --- a/claude/CLAUDE.md +++ b/claude/CLAUDE.md @@ -36,17 +36,28 @@ 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. +- My browser is **Helium** (`/Applications/Helium.app`), a Chromium fork — not Google Chrome. +It holds the live logins, so all browser work attaches to Helium. +When a skill says "the user's real Chrome", read it as Helium. +- Remote debugging comes from the toggle at `helium://inspect/#remote-debugging` — +no restart, tabs and logins survive, one consent prompt. +If it is off, ask me to enable it; do not relaunch the browser. +- That toggle serves no `/json` discovery, so `--cdp 9222` and `--auto-connect` time out. +Read the browser WebSocket URL from Helium's own `DevToolsActivePort` file and pass it explicitly: + +```sh +PF="$HOME/Library/Application Support/net.imput.helium/DevToolsActivePort" +EP="ws://127.0.0.1:$(head -1 "$PF")$(sed -n 2p "$PF")" +``` + +- Default to `/agent-browser` for browser work; attach with `--cdp "$EP" --pin-tab`. 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 ` 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; +Start the daemon first — `chrome-cdp daemon start --endpoint "$EP" --json` — +because it holds one connection, so the consent prompt is answered once per session, not on every attach. +For parallel agents on one browser, `--session ` namespaces the sticky current tab so they do not steal each other's tab. +- Both tools attach to my real browser 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. diff --git a/skills/README.md b/skills/README.md index dc400ab..436a10a 100644 --- a/skills/README.md +++ b/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 diff --git a/skills/apply-workday-leave/SKILL.md b/skills/apply-workday-leave/SKILL.md index 804ca9c..92606a0 100644 --- a/skills/apply-workday-leave/SKILL.md +++ b/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. diff --git a/skills/approve-workday-tasks/SKILL.md b/skills/approve-workday-tasks/SKILL.md index 1890d01..733c945 100644 --- a/skills/approve-workday-tasks/SKILL.md +++ b/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. diff --git a/skills/fill-workday-timesheet/SKILL.md b/skills/fill-workday-timesheet/SKILL.md index 59ea4a0..150076a 100644 --- a/skills/fill-workday-timesheet/SKILL.md +++ b/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. diff --git a/skills/list-week-meetings/SKILL.md b/skills/list-week-meetings/SKILL.md index baff916..5901d49 100644 --- a/skills/list-week-meetings/SKILL.md +++ b/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. diff --git a/skills/login-microsoft-sso/SKILL.md b/skills/login-microsoft-sso/SKILL.md index 7a0f30e..0d76021 100644 --- a/skills/login-microsoft-sso/SKILL.md +++ b/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,18 @@ 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. + The user's browser is **Helium**, not Google Chrome, and `doctor` reads Chrome's port file by default — + so give it Helium's endpoint and start the daemon first (one consent prompt per session): + + ```sh + PF="$HOME/Library/Application Support/net.imput.helium/DevToolsActivePort" + EP="ws://127.0.0.1:$(head -1 "$PF")$(sed -n 2p "$PF")" + chrome-cdp daemon start --endpoint "$EP" --json + ``` + + Then run `chrome-cdp doctor --json`. + If the port file is absent, 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 "" --json` (filters, so it skips scanning the full list). @@ -77,7 +87,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 ` (or the sticky `use`). ## Safety diff --git a/skills/record-engage-activity/SKILL.md b/skills/record-engage-activity/SKILL.md index 19ffb57..d995c9f 100644 --- a/skills/record-engage-activity/SKILL.md +++ b/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. From 496f6cdb5e08e569043d73cf9e109d9fc0191fb0 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Tue, 25 Aug 2026 16:35:15 +0530 Subject: [PATCH 2/2] Move the browser attach recipe out of CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The shared CLAUDE.md loads into every session, so it states policy, not mechanics. The endpoint recipe becomes a script both the rules and the skills call by path. - claude/scripts/browser-endpoint.sh: prints the CDP endpoint, exits 1 with an instruction when the port file is absent. - claude/CLAUDE.md: browser section cut from 25 lines to 10 — which browser, attach do not launch, which tool, one consent prompt, no credentials. - login-microsoft-sso: calls the script instead of repeating the recipe. --- CLAUDE.md | 4 +++- claude/CLAUDE.md | 35 +++++++++-------------------- claude/scripts/browser-endpoint.sh | 29 ++++++++++++++++++++++++ skills/login-microsoft-sso/SKILL.md | 9 ++++---- 4 files changed, 46 insertions(+), 31 deletions(-) create mode 100755 claude/scripts/browser-endpoint.sh diff --git a/CLAUDE.md b/CLAUDE.md index f00148a..b837e64 100644 --- a/CLAUDE.md +++ b/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. diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md index bd4beae..b555626 100644 --- a/claude/CLAUDE.md +++ b/claude/CLAUDE.md @@ -36,28 +36,13 @@ It preserves rendered output, code blocks, tables, and frontmatter. # Interacting with browser -- My browser is **Helium** (`/Applications/Helium.app`), a Chromium fork — not Google Chrome. -It holds the live logins, so all browser work attaches to Helium. -When a skill says "the user's real Chrome", read it as Helium. -- Remote debugging comes from the toggle at `helium://inspect/#remote-debugging` — -no restart, tabs and logins survive, one consent prompt. -If it is off, ask me to enable it; do not relaunch the browser. -- That toggle serves no `/json` discovery, so `--cdp 9222` and `--auto-connect` time out. -Read the browser WebSocket URL from Helium's own `DevToolsActivePort` file and pass it explicitly: - -```sh -PF="$HOME/Library/Application Support/net.imput.helium/DevToolsActivePort" -EP="ws://127.0.0.1:$(head -1 "$PF")$(sed -n 2p "$PF")" -``` - -- Default to `/agent-browser` for browser work; attach with `--cdp "$EP" --pin-tab`. -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. -Start the daemon first — `chrome-cdp daemon start --endpoint "$EP" --json` — -because it holds one connection, so the consent prompt is answered once per session, not on every attach. -For parallel agents on one browser, `--session ` namespaces the sticky current tab so they do not steal each other's tab. -- Both tools attach to my real browser 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. diff --git a/claude/scripts/browser-endpoint.sh b/claude/scripts/browser-endpoint.sh new file mode 100755 index 0000000..ff76c08 --- /dev/null +++ b/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}" diff --git a/skills/login-microsoft-sso/SKILL.md b/skills/login-microsoft-sso/SKILL.md index 0d76021..244fcd5 100644 --- a/skills/login-microsoft-sso/SKILL.md +++ b/skills/login-microsoft-sso/SKILL.md @@ -44,17 +44,16 @@ All commands take `--json`. Parse the envelope and branch on the exit code (see `drive-chrome-cdp`). 1. **Connection.** - The user's browser is **Helium**, not Google Chrome, and `doctor` reads Chrome's port file by default — - so give it Helium's endpoint and start the daemon first (one consent prompt per session): + `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 - PF="$HOME/Library/Application Support/net.imput.helium/DevToolsActivePort" - EP="ws://127.0.0.1:$(head -1 "$PF")$(sed -n 2p "$PF")" + EP="$("$CLAUDE_CONFIG_DIR"/scripts/browser-endpoint.sh)" chrome-cdp daemon start --endpoint "$EP" --json ``` Then run `chrome-cdp doctor --json`. - If the port file is absent, or `ok:false` (connection_failed), + 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.**