mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-12 07:59:02 +02:00
Mechanical regen after the resolver change: −12,628 lines across 52 renders (corpus 952K -> 806K render tokens; tier-2 skills −11-13KB each). Golden per-host ship fixtures refreshed from the fresh claude/codex/factory renders. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
560 lines
25 KiB
Markdown
560 lines
25 KiB
Markdown
---
|
|
name: open-gstack-browser
|
|
preamble-tier: 1
|
|
version: 0.2.0
|
|
description: Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in.
|
|
triggers:
|
|
- open gstack browser
|
|
- launch chromium
|
|
- show me the browser
|
|
allowed-tools:
|
|
- Bash
|
|
- Read
|
|
- AskUserQuestion
|
|
|
|
---
|
|
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
|
|
<!-- Regenerate: bun run gen:skill-docs -->
|
|
|
|
|
|
## When to invoke this skill
|
|
|
|
Opens a visible browser window where you can watch every action in real time.
|
|
The sidebar shows a live activity feed and chat. Anti-bot stealth built in.
|
|
Use when asked to "open gstack browser", "launch browser", "connect chrome",
|
|
"open chrome", "real browser", "launch chrome", "side panel", or "control my browser".
|
|
|
|
Voice triggers (speech-to-text aliases): "show me the browser".
|
|
|
|
## Preamble (run first)
|
|
|
|
```bash
|
|
_SS="$HOME/.claude/skills/gstack/bin/gstack-skill-start"
|
|
[ -x "$_SS" ] || _SS=".claude/skills/gstack/bin/gstack-skill-start"
|
|
"$_SS" --skill "open-gstack-browser" --model "claude" --parent-pid "$PPID" \
|
|
|| echo "SKILL_START: unavailable — stale install; run ./setup or /gstack-upgrade (preamble degraded, continue the user's task)"
|
|
```
|
|
|
|
Read the echoed `KEY: value` STATUS lines — they drive every preamble rule
|
|
below. **Degraded mode:** if `SKILL_START_PROTO: 1` is missing from the output
|
|
(script absent, stale install, or a different protocol number), apply safe
|
|
defaults: treat `SESSION_KIND` as `interactive`, do NOT assume Conductor,
|
|
skip onboarding/telemetry steps (their gates are marker-based, so consent and
|
|
onboarding prompts are DEFERRED to the next healthy run — never lost), tell
|
|
the user to run `./setup` or `/gstack-upgrade`, and proceed with their task.
|
|
Note `SESSION_ID` and `TEL_START` from the output — the Telemetry step needs
|
|
them at skill end.
|
|
|
|
## Plan Mode Safe Operations
|
|
|
|
In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`codex review`, writes to `~/.gstack/`, writes to the plan file, and `open` for generated artifacts.
|
|
|
|
## Skill Invocation During Plan Mode
|
|
|
|
If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; any AskUserQuestion the skill fires is the workflow operating within plan mode, not a violation of it — and a skill whose instructions resolve a question themselves (e.g. a plan-mode auto-select) may legitimately not ask it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode.
|
|
|
|
If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?"
|
|
|
|
If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`.
|
|
|
|
If `UPDATE_CHECK` is `"false"`, skip the next two lines — the update-check binary emits nothing in that mode, so there is no `UPGRADE_AVAILABLE` / `JUST_UPGRADED` output to act on.
|
|
|
|
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined).
|
|
|
|
If output shows `JUST_UPGRADED <from> <to>`: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery.
|
|
|
|
Feature discovery, max one prompt per session:
|
|
- Missing `~/.claude/skills/gstack/.feature-prompted-continuous-checkpoint`: AskUserQuestion for Continuous checkpoint auto-commits. If accepted, run `~/.claude/skills/gstack/bin/gstack-config set checkpoint_mode continuous`. Always touch marker.
|
|
- Missing `~/.claude/skills/gstack/.feature-prompted-model-overlay`: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker.
|
|
|
|
After upgrade prompts, continue workflow.
|
|
|
|
If `WRITING_STYLE_PENDING` is `yes`: ask once about writing style:
|
|
|
|
> v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse?
|
|
|
|
Options:
|
|
- A) Keep the new default (recommended — good writing helps everyone)
|
|
- B) Restore V0 prose — set `explain_level: terse`
|
|
|
|
If A: leave `explain_level` unset (defaults to `default`).
|
|
If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`.
|
|
|
|
Always run (regardless of choice):
|
|
```bash
|
|
rm -f ~/.gstack/.writing-style-prompt-pending
|
|
touch ~/.gstack/.writing-style-prompted
|
|
```
|
|
|
|
Skip if `WRITING_STYLE_PENDING` is `no`.
|
|
|
|
If `LAKE_INTRO` is `no`: say "gstack follows the **Boil the Ocean** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open:
|
|
|
|
```bash
|
|
open https://garryslist.org/posts/boil-the-ocean
|
|
touch ~/.gstack/.completeness-intro-seen
|
|
```
|
|
|
|
Only run `open` if yes. Always run `touch`.
|
|
|
|
If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: ask telemetry once via AskUserQuestion:
|
|
|
|
> Help gstack get better. Share usage data only: skill, duration, crashes, stable device ID. No code or file paths. Your repo name is recorded locally only and stripped before any upload.
|
|
|
|
Options:
|
|
- A) Help gstack get better! (recommended)
|
|
- B) No thanks
|
|
|
|
If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community`
|
|
|
|
If B: ask follow-up:
|
|
|
|
> Anonymous mode sends only aggregate usage, no unique ID.
|
|
|
|
Options:
|
|
- A) Sure, anonymous is fine
|
|
- B) No thanks, fully off
|
|
|
|
If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous`
|
|
If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off`
|
|
|
|
Always run:
|
|
```bash
|
|
touch ~/.gstack/.telemetry-prompted
|
|
```
|
|
|
|
Skip if `TEL_PROMPTED` is `yes`.
|
|
|
|
If `PROACTIVE_PROMPTED` is `no` AND `TEL_PROMPTED` is `yes`: ask once:
|
|
|
|
> Let gstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs?
|
|
|
|
Options:
|
|
- A) Keep it on (recommended)
|
|
- B) Turn it off — I'll type /commands myself
|
|
|
|
If A: run `~/.claude/skills/gstack/bin/gstack-config set proactive true`
|
|
If B: run `~/.claude/skills/gstack/bin/gstack-config set proactive false`
|
|
|
|
Always run:
|
|
```bash
|
|
touch ~/.gstack/.proactive-prompted
|
|
```
|
|
|
|
Skip if `PROACTIVE_PROMPTED` is `yes`.
|
|
|
|
## First-run guidance (one-time)
|
|
|
|
If `ACTIVATED` is `no` (first skill run on this machine) AND the preamble printed a non-empty `FIRST_TASK:` value that is NOT `nongit`: show ONE short, project-specific line mapped from the token, as a heads-up, then CONTINUE with whatever the user actually asked — do NOT halt their task. Map the token: `greenfield` → "Fresh repo — shape it first with `/spec` or `/office-hours`." `code_node`/`code_python`/`code_rust`/`code_go`/`code_ruby`/`code_ios` → "There's code here — `/qa` to see it work, or `/investigate` if something's off." `branch_ahead` → "Unshipped work on this branch — `/review` then `/ship`." `dirty_default` → "Uncommitted changes — `/review` before committing." `clean_default` → "Pick one: `/spec`, `/investigate`, or `/qa`." Then substitute the token you saw for TASK_TOKEN and run (best-effort), and mark activated:
|
|
```bash
|
|
~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type first_task_scaffold_shown --skill "TASK_TOKEN" --outcome shown 2>/dev/null || true
|
|
touch ~/.gstack/.activated 2>/dev/null || true
|
|
```
|
|
|
|
If `ACTIVATED` is `no` but `FIRST_TASK:` is empty or `nongit` (headless, non-git, or nothing actionable): show nothing, just run `touch ~/.gstack/.activated 2>/dev/null || true`.
|
|
|
|
Else if `ACTIVATED` is `yes` AND `FIRST_LOOP_SHOWN` is `no`: say once as a heads-up (then continue):
|
|
|
|
> Tip: gstack pays off when you complete one loop — **plan → review → ship**. A common first loop: `/office-hours` or `/spec` to shape it, `/plan-eng-review` to lock it, then `/ship`.
|
|
|
|
Then run `touch ~/.gstack/.first-loop-tip-shown 2>/dev/null || true`.
|
|
|
|
Skip this section if `ACTIVATED` and `FIRST_LOOP_SHOWN` are both `yes`.
|
|
|
|
If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`:
|
|
Check if a CLAUDE.md file exists in the project root. If it does not exist, create it.
|
|
|
|
Use AskUserQuestion:
|
|
|
|
> gstack works best when your project's CLAUDE.md includes skill routing rules.
|
|
|
|
Options:
|
|
- A) Add routing rules to CLAUDE.md (recommended)
|
|
- B) No thanks, I'll invoke skills manually
|
|
|
|
If A: Append this section to the end of CLAUDE.md:
|
|
|
|
```markdown
|
|
|
|
## Skill routing
|
|
|
|
When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.
|
|
|
|
Key routing rules:
|
|
- Product ideas/brainstorming → invoke /office-hours
|
|
- Strategy/scope → invoke /plan-ceo-review
|
|
- Architecture → invoke /plan-eng-review
|
|
- Design system/plan review → invoke /design-consultation or /plan-design-review
|
|
- Full review pipeline → invoke /autoplan
|
|
- Bugs/errors → invoke /investigate
|
|
- QA/testing site behavior → invoke /qa or /qa-only
|
|
- Code review/diff check → invoke /review
|
|
- Visual polish → invoke /design-review
|
|
- Ship/deploy/PR → invoke /ship or /land-and-deploy
|
|
- Save progress → invoke /context-save
|
|
- Resume context → invoke /context-restore
|
|
- Author a backlog-ready spec/issue → invoke /spec
|
|
```
|
|
|
|
Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"`
|
|
|
|
If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` and say they can re-enable with `gstack-config set routing_declined false`.
|
|
|
|
This only happens once per project. Skip if `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`.
|
|
|
|
If `VENDORED_GSTACK` is `yes`, warn once via AskUserQuestion unless `~/.gstack/.vendoring-warned-$SLUG` exists:
|
|
|
|
> This project has gstack vendored in `.claude/skills/gstack/`. Vendoring is deprecated.
|
|
> Migrate to team mode?
|
|
|
|
Options:
|
|
- A) Yes, migrate to team mode now
|
|
- B) No, I'll handle it myself
|
|
|
|
If A:
|
|
1. Run `git rm -r .claude/skills/gstack/`
|
|
2. Run `echo '.claude/skills/gstack/' >> .gitignore`
|
|
3. Run `~/.claude/skills/gstack/bin/gstack-team-init required` (or `optional`)
|
|
4. Run `git add .claude/ .gitignore CLAUDE.md && git commit -m "chore: migrate gstack from vendored to team mode"`
|
|
5. Tell the user: "Done. Each developer now runs: `cd ~/.claude/skills/gstack && ./setup --team`"
|
|
|
|
If B: say "OK, you're on your own to keep the vendored copy up to date."
|
|
|
|
Always run (regardless of choice):
|
|
```bash
|
|
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
|
|
touch ~/.gstack/.vendoring-warned-${SLUG:-unknown}
|
|
```
|
|
|
|
If marker exists, skip.
|
|
|
|
If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an
|
|
AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
|
- Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option.
|
|
- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro.
|
|
- Focus on completing the task and reporting results via prose output.
|
|
- End with a completion report: what shipped, decisions made, anything uncertain.
|
|
|
|
## Artifacts Sync (skill start)
|
|
|
|
The skill-start output above already ran artifacts sync. Act on its lines:
|
|
GBrain hint text (if present) tells you when to prefer `gbrain` over Grep;
|
|
`ARTIFACTS_SYNC:` reports sync health (`off`, `mode=... | queue=N`,
|
|
`remote-mode`, or a restore hint naming `gstack-brain-restore`).
|
|
|
|
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
|
|
|
|
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
|
|
|
|
Options:
|
|
- A) Everything allowlisted (recommended)
|
|
- B) Only artifacts
|
|
- C) Decline, keep everything local
|
|
|
|
After answer:
|
|
|
|
```bash
|
|
# Chosen mode: full | artifacts-only | off
|
|
~/.claude/skills/gstack/bin/gstack-config set artifacts_sync_mode <choice>
|
|
~/.claude/skills/gstack/bin/gstack-config set artifacts_sync_mode_prompted true
|
|
```
|
|
|
|
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
|
|
|
|
## Model-Specific Behavioral Patch (claude)
|
|
|
|
The following nudges are tuned for the claude model family. They are
|
|
**subordinate** to skill workflow, STOP points, AskUserQuestion gates, plan-mode
|
|
safety, and /ship review gates. If a nudge below conflicts with skill instructions,
|
|
the skill wins. Treat these as preferences, not rules.
|
|
|
|
**Todo-list discipline.** When working through a multi-step plan, mark each task
|
|
complete individually as you finish it. Do not batch-complete at the end. If a task
|
|
turns out to be unnecessary, mark it skipped with a one-line reason.
|
|
|
|
**Think before heavy actions.** For complex operations (refactors, migrations,
|
|
non-trivial new features), briefly state your approach before executing. This lets
|
|
the user course-correct cheaply instead of mid-flight.
|
|
|
|
**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell
|
|
equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer.
|
|
|
|
## Voice
|
|
|
|
Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler.
|
|
|
|
No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do.
|
|
|
|
The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides.
|
|
|
|
## Completion Status Protocol
|
|
|
|
When completing a skill workflow, report status using one of:
|
|
- **DONE** — completed with evidence.
|
|
- **DONE_WITH_CONCERNS** — completed, but list concerns.
|
|
- **BLOCKED** — cannot proceed; state blocker and what was tried.
|
|
- **NEEDS_CONTEXT** — missing info; state exactly what is needed.
|
|
|
|
Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: `STATUS`, `REASON`, `ATTEMPTED`, `RECOMMENDATION`.
|
|
|
|
## Operational Self-Improvement
|
|
|
|
Before completing, review the session for durable learnings and log each one —
|
|
this step ALWAYS runs, it is not conditional on something feeling noteworthy
|
|
(#2402: 43 of 44 learnings came from explicit /learn because "if you
|
|
discovered" read as optional). A durable learning is a project quirk, command
|
|
fix, pitfall, or pattern that would save 5+ minutes in a future session. If
|
|
the review genuinely surfaces none, state "No durable learnings this session"
|
|
in your completion summary — an explicit empty result, not a skipped step.
|
|
|
|
```bash
|
|
~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}'
|
|
```
|
|
|
|
Do not log obvious facts or one-time transient errors.
|
|
|
|
## Telemetry (run last)
|
|
|
|
After workflow completion, log telemetry with ONE command. OUTCOME is
|
|
success/error/abort/unknown; `SESSION_ID` and `TEL_START` are the values the
|
|
preamble's skill-start output echoed. It also drains the artifacts-sync queue
|
|
(the former skill-end sync step — do not run gstack-brain-sync separately).
|
|
|
|
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes telemetry to
|
|
`~/.gstack/analytics/`, matching preamble analytics writes.
|
|
|
|
```bash
|
|
~/.claude/skills/gstack/bin/gstack-skill-end --skill "open-gstack-browser" --outcome OUTCOME \
|
|
--session-id "SESSION_ID" --tel-start "TEL_START" --used-browse USED_BROWSE \
|
|
--error-message "ERROR_MESSAGE" --failed-step "FAILED_STEP" 2>/dev/null || true
|
|
```
|
|
|
|
Replace `OUTCOME` and `USED_BROWSE` (yes/no) before running; substitute
|
|
`SESSION_ID`/`TEL_START` from the skill-start echoes. `ERROR_MESSAGE`/`FAILED_STEP`
|
|
are "" unless outcome is error. If the command is missing (stale install), skip
|
|
telemetry — it never blocks the workflow.
|
|
|
|
## Plan Status Footer
|
|
|
|
Skills that run plan reviews (`/plan-*-review`, `/codex review`) include the EXIT PLAN MODE GATE blocking checklist at the end of the skill, which verifies the plan file ends with `## GSTACK REVIEW REPORT` before ExitPlanMode is called. Skills that don't run plan reviews (operational skills like `/ship`, `/qa`, `/review`) typically don't operate in plan mode and have no review report to verify; this footer is a no-op for them. Writing the plan file is the one edit allowed in plan mode.
|
|
|
|
# /open-gstack-browser — Launch GStack Browser
|
|
|
|
Launch GStack Browser — AI-controlled Chromium with the sidebar extension,
|
|
anti-bot stealth, and custom branding. You see every action in real time.
|
|
|
|
## SETUP (run this check BEFORE any browse command)
|
|
|
|
```bash
|
|
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
|
B=""
|
|
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
|
|
[ -z "$B" ] && B="$HOME/.claude/skills/gstack/browse/dist/browse"
|
|
if [ -x "$B" ]; then
|
|
echo "READY: $B"
|
|
else
|
|
echo "NEEDS_SETUP"
|
|
fi
|
|
```
|
|
|
|
If `NEEDS_SETUP`:
|
|
1. Tell the user: "gstack 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:
|
|
```bash
|
|
if ! command -v bun >/dev/null 2>&1; then
|
|
BUN_VERSION="1.3.10"
|
|
BUN_INSTALL_SHA="bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd"
|
|
tmpfile=$(mktemp)
|
|
curl -fsSL "https://bun.sh/install" -o "$tmpfile"
|
|
actual_sha=$(shasum -a 256 "$tmpfile" | awk '{print $1}')
|
|
if [ "$actual_sha" != "$BUN_INSTALL_SHA" ]; then
|
|
echo "ERROR: bun install script checksum mismatch" >&2
|
|
echo " expected: $BUN_INSTALL_SHA" >&2
|
|
echo " got: $actual_sha" >&2
|
|
rm "$tmpfile"; exit 1
|
|
fi
|
|
BUN_VERSION="$BUN_VERSION" bash "$tmpfile"
|
|
rm "$tmpfile"
|
|
fi
|
|
```
|
|
|
|
## 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.
|
|
|
|
```bash
|
|
# Kill any existing browse server
|
|
if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.gstack/browse.json" ]; then
|
|
_OLD_PID=$(cat "$(git rev-parse --show-toplevel)/.gstack/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)/.gstack/browse.json"
|
|
fi
|
|
# Clean Chromium profile locks (can persist after crashes)
|
|
_PROFILE_DIR="$HOME/.gstack/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
|
|
|
|
```bash
|
|
$B connect
|
|
```
|
|
|
|
This launches GStack Browser (rebranded Chromium) in headed mode with:
|
|
- A visible window you can watch (not your regular Chrome — it stays untouched)
|
|
- The gstack sidebar extension auto-loaded via `launchPersistentContext`
|
|
- Anti-bot stealth patches (sites like Google and NYTimes work without captchas)
|
|
- Custom user agent and GStack Browser branding in Dock/menu bar
|
|
- A sidebar agent process for chat commands
|
|
|
|
The `connect` command auto-discovers the extension from the gstack 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
|
|
|
|
```bash
|
|
$B status
|
|
```
|
|
|
|
Confirm the output shows `Mode: headed`. Read the port from the state file:
|
|
|
|
```bash
|
|
cat "$(git rev-parse --show-toplevel 2>/dev/null)/.gstack/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:
|
|
|
|
```bash
|
|
_EXT_PATH=""
|
|
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
|
[ -n "$_ROOT" ] && [ -f "$_ROOT/.claude/skills/gstack/extension/manifest.json" ] && _EXT_PATH="$_ROOT/.claude/skills/gstack/extension"
|
|
[ -z "$_EXT_PATH" ] && [ -f "$HOME/.claude/skills/gstack/extension/manifest.json" ] && _EXT_PATH="$HOME/.claude/skills/gstack/extension"
|
|
echo "EXTENSION_PATH: ${_EXT_PATH:-NOT FOUND}"
|
|
```
|
|
|
|
## Step 3: Guide the user to the Side Panel
|
|
|
|
Use AskUserQuestion:
|
|
|
|
> Chrome is launched with gstack 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 gstack icon if the extension loaded successfully
|
|
> 2. Click the **puzzle piece** → find **gstack browse** → click the **pin icon**
|
|
> 3. Click the pinned **gstack 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 **"gstack 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 gstack 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:
|
|
|
|
```bash
|
|
$B goto https://news.ycombinator.com
|
|
```
|
|
|
|
Wait 2 seconds, then:
|
|
|
|
```bash
|
|
$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 gstack skill (`/qa`, `/design-review`, `/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:**
|
|
> - `/qa` runs its full test suite in the visible browser — you see every page
|
|
> load, every click, every assertion
|
|
> - `/design-review` takes screenshots in the real browser — same pixels you see
|
|
> - `/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.
|