connect-chrome

Pre-check

Check the SessionStart hook output in this conversation context for ADEEL_AUTO_UPDATE=. If it says ADEEL_AUTO_UPDATE=false, use AskUserQuestion to ask: "Auto-updates are off. Run /adeel-update to enable?" If yes, invoke /adeel-update. If ADEEL_AUTO_UPDATE=true or not found, proceed directly without mentioning it.

Preamble (run first)

mkdir -p $HOME/.adeel/sessions
touch $HOME/.adeel/sessions/"$PPID"
_SESSIONS=$(find $HOME/.adeel/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
find $HOME/.adeel/sessions -mmin +120 -type f -delete 2>/dev/null || true
_CONTRIB=$(${CLAUDE_PLUGIN_ROOT}/bin/adeel-config get adeel_contributor 2>/dev/null || true)
_PROACTIVE=$(${CLAUDE_PLUGIN_ROOT}/bin/adeel-config get proactive 2>/dev/null || echo "true")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
echo "PROACTIVE: $_PROACTIVE"
source <(${CLAUDE_PLUGIN_ROOT}/bin/adeel-repo-mode 2>/dev/null) || true
REPO_MODE=${REPO_MODE:-unknown}
echo "REPO_MODE: $REPO_MODE"
echo "LAKE_INTRO: $_LAKE_SEEN"
_TEL=$(${CLAUDE_PLUGIN_ROOT}/bin/adeel-config get telemetry 2>/dev/null || true)
_TEL_PROMPTED=$([ -f $HOME/.adeel/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
echo "TELEMETRY: ${_TEL:-off}"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
mkdir -p $HOME/.adeel/analytics
echo '{"skill":"connect-chrome","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}'  >> $HOME/.adeel/analytics/skill-usage.jsonl 2>/dev/null || true
# zsh-compatible: use find instead of glob to avoid NOMATCH error

If PROACTIVE is "false", do not proactively suggest adeel skills — only invoke them when the user explicitly asks. The user opted out of proactive suggestions.

If LAKE_INTRO is no: Before continuing, introduce the Completeness Principle. Tell the user: "adeel follows the Go all the way principle — always do the complete Then offer to open the essay in their default browser:

Only run open if the user says yes. Always run touch to mark as seen. This only happens once.

If TEL_PROMPTED is no AND LAKE_INTRO is yes: After the lake intro is handled, ask the user about telemetry. Use AskUserQuestion:

Help adeel get better! Community mode shares usage data (which skills you use, how long they take, crash info) with a stable device ID so we can track trends and fix bugs faster. No code, file paths, or repo names are ever sent. Change anytime with adeel-config set telemetry off.

Options:

• A) Help adeel get better! (recommended)
• B) No thanks

If A: run ${CLAUDE_PLUGIN_ROOT}/bin/adeel-config set telemetry community

If B: ask a follow-up AskUserQuestion:

How about anonymous mode? We just learn that someone used adeel — no unique ID, no way to connect sessions. Just a counter that helps us know if anyone's out there.

Options:

• A) Sure, anonymous is fine
• B) No thanks, fully off

If B→A: run ${CLAUDE_PLUGIN_ROOT}/bin/adeel-config set telemetry anonymous If B→B: run ${CLAUDE_PLUGIN_ROOT}/bin/adeel-config set telemetry off

Always run:

touch $HOME/.adeel/.telemetry-prompted

This only happens once. If TEL_PROMPTED is yes, skip this entirely.

AskUserQuestion Format

ALWAYS follow this structure for every AskUserQuestion call:

1. Re-ground: State the project, the current branch (use the _BRANCH value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend: RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.
4. Options: Lettered options: A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)

Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.

Per-skill instructions may add additional formatting rules on top of this baseline.

Completeness Principle — Go all the way

AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+adeel. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.

Effort reference — always show both scales:

Task type	Human team	CC+adeel	Compression
Boilerplate	2 days	15 min	~100x
Tests	1 day	15 min	~50x
Feature	1 week	30 min	~30x
Bug fix	4 hours	15 min	~20x

Include Completeness: X/10 for each option (10=all edge cases, 7=happy path, 3=shortcut).

Repo Ownership — See Something, Say Something

REPO_MODE controls how to handle issues outside your branch:

• solo — You own everything. Investigate and offer to fix proactively.
• collaborative / unknown — Flag via AskUserQuestion, don't fix (may be someone else's).

Always flag anything that looks wrong — one sentence, what you noticed and its impact.

Search Before Building

Before building anything unfamiliar, search first. See ~/.claude/skills/adeel/ETHOS.md.

• Layer 1 (tried and true) — don't reinvent. Layer 2 (new and popular) — scrutinize. Layer 3 (first principles) — prize above all.

Eureka: When first-principles reasoning contradicts conventional wisdom, name it and log:

jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> $HOME/.adeel/analytics/eureka.jsonl 2>/dev/null || true

Contributor Mode

If _CONTRIB is true: you are in contributor mode. At the end of each major workflow step, rate your adeel experience 0-10. If not a 10 and there's an actionable bug or improvement — file a field report.

File only: adeel tooling bugs where the input was reasonable but adeel failed. Skip: user app bugs, network errors, auth failures on user's site.

To file: write $HOME/.adeel/contributor-logs/{slug}.md:

# {Title}
**What I tried:** {action} | **What happened:** {result} | **Rating:** {0-10}
## Repro
1. {step}
## What would make this a 10
{one sentence}
**Date:** {YYYY-MM-DD} | **Version:** {version} | **Skill:** /{skill}

Slug: lowercase hyphens, max 60 chars. Skip if exists. Max 3/session. File inline, don't stop.

Completion Status Protocol

When completing a skill workflow, report status using one of:

• DONE — All steps completed successfully. Evidence provided for each claim.
• DONE_WITH_CONCERNS — Completed, but with issues the user should know about. List each concern.
• BLOCKED — Cannot proceed. State what is blocking and what was tried.
• NEEDS_CONTEXT — Missing information required to continue. State exactly what you need.

Escalation

It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."

Bad work is worse than no work. You will not be penalized for escalating.

• If you have attempted a task 3 times without success, STOP and escalate.
• If you are uncertain about a security-sensitive change, STOP and escalate.
• If the scope of work exceeds what you can verify, STOP and escalate.

Escalation format:

STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]

Telemetry (run last)

After the skill workflow completes (success, error, or abort), log the telemetry event. Determine the skill name from the name: field in this file's YAML frontmatter. Determine the outcome from the workflow result (success if completed normally, error if it failed, abort if the user interrupted).

PLAN MODE EXCEPTION — ALWAYS RUN: This command writes telemetry to $HOME/.adeel/analytics/ (user config directory, not project files). The skill preamble already writes to the same directory — this is the same pattern. Skipping this command loses session duration and outcome data.

Run this bash:

_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - _TEL_START ))
rm -f $HOME/.adeel/analytics/.pending-"$_SESSION_ID" 2>/dev/null || true
  --skill "SKILL_NAME" --duration "$_TEL_DUR" --outcome "OUTCOME" \
  --used-browse "USED_BROWSE" --session-id "$_SESSION_ID" 2>/dev/null &

Replace SKILL_NAME with the actual skill name from frontmatter, OUTCOME with success/error/abort, and USED_BROWSE with true/false based on whether $B was used. If you cannot determine the outcome, use "unknown". This runs in the background and never blocks the user.

Plan Status Footer

When you are in plan mode and about to call ExitPlanMode:

1. Check if the plan file already has a ## ADEEL REVIEW REPORT section.
2. If it DOES — skip (a review skill already wrote a richer report).
3. If it does NOT — run this command:

```bash ${CLAUDE_PLUGIN_ROOT}/bin/adeel-review-read ```

Then write a ## ADEEL REVIEW REPORT section to the end of the plan file:

• If the output contains review entries (JSONL lines before ---CONFIG---): format the standard report table with runs/status/findings per skill, same format as the review skills use.
• If the output is NO_REVIEWS or empty: write this placeholder table:

```markdown

ADEEL REVIEW REPORT

Review	Trigger	Why	Runs	Status	Findings
CEO Review	`/adeel:plan-ceo-review`	Scope & strategy	0	—	—
Codex Review	`/adeel:codex review`	Independent 2nd opinion	0	—	—
Eng Review	`/adeel:plan-eng-review`	Architecture & tests (required)	0	—	—
Design Review	`/adeel:plan-design-review`	UI/UX gaps	0	—	—

VERDICT: NO REVIEWS YET — run `/adeel:autoplan` for full review pipeline, or individual reviews above. ```

PLAN MODE EXCEPTION — ALWAYS RUN: This writes to the plan file, which is the one file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status.

/adeel:connect-chrome — Launch Real Chrome with Side Panel

Connect Claude to a visible Chrome window with the adeel extension auto-loaded. You see every click, every navigation, every action in real time.

SETUP (run this check BEFORE any browse command)

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/adeel/browse/dist/browse" ] && B="$_ROOT/.claude/skills/adeel/browse/dist/browse"
[ -z "$B" ] && B=${CLAUDE_PLUGIN_ROOT}/browse/dist/browse
if [ -x "$B" ]; then
  echo "READY: $B"
else
  echo "NEEDS_SETUP"
fi

If NEEDS_SETUP:

1. Tell the user: "adeel browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
2. Run: cd <SKILL_DIR> && ./setup
3. If bun is not installed: curl -fsSL https://bun.sh/install | bash

Step 0: Pre-flight cleanup

Before connecting, kill any stale browse servers and clean up lock files that may have persisted from a crash. This prevents "already connected" false positives and Chromium profile lock conflicts.

# Kill any existing browse server
if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.adeel/browse.json" ]; then
  _OLD_PID=$(cat "$(git rev-parse --show-toplevel)/.adeel/browse.json" 2>/dev/null | grep -o '"pid":[0-9]*' | grep -o '[0-9]*')
  [ -n "$_OLD_PID" ] && kill "$_OLD_PID" 2>/dev/null || true
  sleep 1
  [ -n "$_OLD_PID" ] && kill -9 "$_OLD_PID" 2>/dev/null || true
  rm -f "$(git rev-parse --show-toplevel)/.adeel/browse.json"
fi
# Clean Chromium profile locks (can persist after crashes)
_PROFILE_DIR="$HOME/.adeel/chromium-profile"
for _LF in SingletonLock SingletonSocket SingletonCookie; do
  rm -f "$_PROFILE_DIR/$_LF" 2>/dev/null || true
done
echo "Pre-flight cleanup done"

Step 1: Connect

$B connect

This launches Playwright's bundled Chromium in headed mode with:

• A visible window you can watch (not your regular Chrome — it stays untouched)
• The adeel Chrome extension auto-loaded via launchPersistentContext
• A golden shimmer line at the top of every page so you know which window is controlled
• A sidebar agent process for chat commands

The connect command auto-discovers the extension from the adeel install directory. It always uses port 34567 so the extension can auto-connect.

After connecting, print the full output to the user. Confirm you see Mode: headed in the output.

If the output shows an error or the mode is not headed, run $B status and share the output with the user before proceeding.

Step 2: Verify

$B status

Confirm the output shows Mode: headed. Read the port from the state file:

cat "$(git rev-parse --show-toplevel 2>/dev/null)/.adeel/browse.json" 2>/dev/null | grep -o '"port":[0-9]*' | grep -o '[0-9]*'

The port should be 34567. If it's different, note it — the user may need it for the Side Panel.

Also find the extension path so you can help the user if they need to load it manually:

_EXT_PATH=""
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
[ -n "$_ROOT" ] && [ -f "$_ROOT/${CLAUDE_PLUGIN_ROOT}/extension/manifest.json" ] && _EXT_PATH="$_ROOT/${CLAUDE_PLUGIN_ROOT}/extension"
[ -z "$_EXT_PATH" ] && [ -f "$HOME/${CLAUDE_PLUGIN_ROOT}/extension/manifest.json" ] && _EXT_PATH="$HOME/${CLAUDE_PLUGIN_ROOT}/extension"
echo "EXTENSION_PATH: ${_EXT_PATH:-NOT FOUND}"

Step 3: Guide the user to the Side Panel

Use AskUserQuestion:

Chrome is launched with adeel control. You should see Playwright's Chromium (not your regular Chrome) with a golden shimmer line at the top of the page.

The Side Panel extension should be auto-loaded. To open it:

1. Look for the puzzle piece icon (Extensions) in the toolbar — it may already show the adeel icon if the extension loaded successfully
2. Click the puzzle piece → find adeel browse → click the pin icon
3. Click the pinned adeel icon in the toolbar
4. The Side Panel should open on the right showing a live activity feed

Port: 34567 (auto-detected — the extension connects automatically in the Playwright-controlled Chrome).

Options:

• A) I can see the Side Panel — let's go!
• B) I can see Chrome but can't find the extension
• C) Something went wrong

If B: Tell the user:

The extension is loaded into Playwright's Chromium at launch time, but sometimes it doesn't appear immediately. Try these steps:

1. Type chrome://extensions in the address bar
2. Look for "adeel browse" — it should be listed and enabled
3. If it's there but not pinned, go back to any page, click the puzzle piece icon, and pin it
4. If it's NOT listed at all, click "Load unpacked" and navigate to:
   • Press Cmd+Shift+G in the file picker dialog
   • Paste this path: {EXTENSION_PATH} (use the path from Step 2)
   • Click Select

After loading, pin it and click the icon to open the Side Panel.

If the Side Panel badge stays gray (disconnected), click the adeel icon and enter port 34567 manually.

If C:

1. Run $B status and show the output
2. If the server is not healthy, re-run Step 0 cleanup + Step 1 connect
3. If the server IS healthy but the browser isn't visible, try $B focus
4. If that fails, ask the user what they see (error message, blank screen, etc.)

Step 4: Demo

After the user confirms the Side Panel is working, run a quick demo:

$B goto https://news.ycombinator.com

Wait 2 seconds, then:

$B snapshot -i

Tell the user: "Check the Side Panel — you should see the goto and snapshot commands appear in the activity feed. Every command Claude runs shows up here in real time."

Step 5: Sidebar chat

After the activity feed demo, tell the user about the sidebar chat:

The Side Panel also has a chat tab. Try typing a message like "take a snapshot and describe this page." A sidebar agent (a child Claude instance) executes your request in the browser — you'll see the commands appear in the activity feed as they happen.

The sidebar agent can navigate pages, click buttons, fill forms, and read content. Each task gets up to 5 minutes. It runs in an isolated session, so it won't interfere with this Claude Code window.

Step 6: What's next

Tell the user:

You're all set! Here's what you can do with the connected Chrome:

Watch Claude work in real time:

• Run any adeel skill (/adeel:qa, /adeel:design-review, /adeel:benchmark) and watch every action happen in the visible Chrome window + Side Panel feed
• No cookie import needed — the Playwright browser shares its own session

Control the browser directly:

• Sidebar chat — type natural language in the Side Panel and the sidebar agent executes it (e.g., "fill in the login form and submit")
• Browse commands — $B goto <url>, $B click <sel>, $B fill <sel> <val>, $B snapshot -i — all visible in Chrome + Side Panel

Window management:

• $B focus — bring Chrome to the foreground anytime
• $B disconnect — close headed Chrome and return to headless mode

What skills look like in headed mode:

• /adeel:qa runs its full test suite in the visible browser — you see every page load, every click, every assertion
• /adeel:design-review takes screenshots in the real browser — same pixels you see
• /adeel:benchmark measures performance in the headed browser

Then proceed with whatever the user asked to do. If they didn't specify a task, ask what they'd like to test or browse.