timurgaleev/vibestack / skills/open-browser
open-browser
UnverifiedOpen a visible browser window you can watch while the agent drives it, with a live activity sidebar.
If this session was compacted, the copy of this skill in context may be cut off.
Read ${CLAUDE_SKILL_DIR}/SKILL.md from disk and resume at the step you are on.
When to invoke
Use when asked to "open browser", "launch browser", "connect chrome", "open chrome", "real browser", "launch chrome", "side panel", or "control my browser".
Preamble
eval "$("${VIBESTACK_HOME:-$HOME/.vibestack}/bin/vibe-slug" 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
_LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
echo "LEARNINGS: $_LEARN_COUNT entries loaded"
if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
"${VIBESTACK_HOME:-$HOME/.vibestack}/bin/vibe-learnings-search" --limit 5 2>/dev/null || true
fi
else
echo "LEARNINGS: none yet"
fi
{{include lib/snippets/session-host.md}}
{{include lib/snippets/decision-brief.md}}
{{include lib/snippets/working-protocols.md}}
{{include lib/snippets/state-protocols.md}}
/open-browser — Launch vibestack Browser
Launch vibestack Browser — AI-controlled Chromium with the sidebar extension, anti-bot stealth, and real-time visibility. You see every action as it happens.
SETUP (run this check BEFORE any browse command)
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
# install renders each skill to <root>/skills/<name>/ and links its bin/ — there
# is no skills/vibestack/ directory and no dist/browse, so the previous paths
# could never resolve and this skill always dead-ended at NEEDS_SETUP.
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/browse/bin/vibe-browse" ] && B="$_ROOT/.claude/skills/browse/bin/vibe-browse"
[ -z "$B" ] && [ -x "${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/open-browser}/../browse/bin/vibe-browse" ] && B="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/open-browser}/../browse/bin/vibe-browse"
[ -z "$B" ] && B="$(command -v vibe-browse || true)"
if [ -x "$B" ]; then echo "READY: $B"; echo "BROWSE_BIN: $B"; else echo "NEEDS_SETUP"; fi
Every Bash call starts a fresh shell, so $B is unset in every later block.
A block that runs a browse command starts with B='<BROWSE_BIN>': replace
<BROWSE_BIN> with the path printed on the BROWSE_BIN: line.
If NEEDS_SETUP, or a later $B connect prints BROWSE_NOT_AVAILABLE, stop
and name the cause it printed. The browse daemon ships with vibestack under
browse/; what can be missing is its runtime:
bun not found— the headed browser needs the full daemon, which runs on bun. Install bun, then re-run.dependencies not installed— runbun installin the vibestack checkout (the path it printed); that also fetches Playwright's Chromium on first use.- the launcher itself is missing — the install skipped the browse skill; re-run
./install.
The stateless fallback shim (node + npm) cannot open a headed window, so it is
no workaround here. See docs/external-tools.md.
Step 0: Check for a running browse daemon
A running browse daemon may hold open tabs, cookies and signed-in sessions —
cookies imported with /setup-browser-cookies, a remote agent paired through
/pair-agent — and replacing it loses all of them. Never kill it, and never
delete its state file, to get it out of the way. Probe without starting one
(BROWSE_NO_AUTOSTART=1 keeps status from booting a daemon):
B='<BROWSE_BIN>'
_STATUS=$(BROWSE_NO_AUTOSTART=1 $B status 2>&1); _STATUS_RC=$?
printf '%s\n' "$_STATUS" | head -5
if [ "$_STATUS_RC" -ne 0 ]; then echo "DAEMON: none"
elif printf '%s' "$_STATUS" | grep -q 'Mode: headed'; then echo "DAEMON: headed"
else echo "DAEMON: live"; fi
-
DAEMON: none: no daemon answered. Run Step 1's plain$B connect. Do not delete the Chromium profile's lock files yourself: another project's vibestack Browser may hold them. The CLI cleans up stale state itself — a lock whose browser is gone, or an orphaned browser whose daemon died — and it refuses, killing and deleting nothing, when a live browser it does not own holds the profile or a daemon is alive but too busy to answer. If it refuses, show its output and stop. -
DAEMON: headed: vibestack Browser is already open. Step 1's plain$B connectreports that; continue to Step 2. -
DAEMON: live: a headless daemon is running. WithSESSION_KIND: spawnedorheadless, do not ask and do not replace it. Print this and stop:B='<BROWSE_BIN>' printf 'Live browse daemon left running. Run %s stop, then re-run /open-browser to replace it.\n' "$B"Otherwise AskUserQuestion. Replacing the daemon cannot be undone:
"A browse daemon is already running (tabs and logins may be active). Opening vibestack Browser replaces it, and everything in that daemon is lost."
RECOMMENDATION: Choose B unless you are done with the running session.
Options:
- A) Replace it (runs
$B connect --force-restart; its tabs, cookies and logins are lost) - B) Keep it running and stop here
Only an explicit A runs Step 1 with
--force-restart. On B, or on a reply that is not clearly A, print the "Live browse daemon left running" line above and stop. - A) Replace it (runs
Step 1: Connect
B='<BROWSE_BIN>'
$B connect
After an explicit A in Step 0, and only then:
B='<BROWSE_BIN>'
$B connect --force-restart
This launches vibestack Browser (rebranded Chromium) in headed mode with:
- A visible window you can watch (not your regular Chrome — it stays untouched)
- The sidebar extension auto-loaded via
launchPersistentContext - Anti-bot stealth patches (sites like Google and NYTimes work without captchas)
- Custom user agent in Dock/menu bar
- A Side Panel whose main surface is a real
claudeterminal (a PTY on this machine), with browser quick-action buttons above it
The connect command auto-discovers the extension from the 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='<BROWSE_BIN>'
$B status
Confirm the output shows Mode: headed. Read the port from the state file:
_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
_STATE_FILE=""
[ -n "$_REPO_ROOT" ] && [ -f "$_REPO_ROOT/.vibestack/browse.json" ] && _STATE_FILE="$_REPO_ROOT/.vibestack/browse.json"
[ -z "$_STATE_FILE" ] && _STATE_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/browse.json"
grep -o '"port":[0-9]*' "$_STATE_FILE" 2>/dev/null | 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)
# Same correction as the binary above: the extension lives in the checkout, and
# the skill reaches it through the repo root, never through a skills/vibestack/
# directory that install does not create.
[ -n "$_ROOT" ] && [ -f "$_ROOT/extension/manifest.json" ] && _EXT_PATH="$_ROOT/extension"
[ -z "$_EXT_PATH" ] && [ -f "${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/open-browser}/extension/manifest.json" ] && _EXT_PATH="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/open-browser}/extension"
echo "EXTENSION_PATH: ${_EXT_PATH:-NOT FOUND}"
Step 3: Guide the user to the Side Panel
Use AskUserQuestion:
Chrome is launched with vibestack control. You should see Playwright's Chromium (not your regular Chrome) with a shimmer line at the top of the page.
The Side Panel extension should be auto-loaded. To open it:
- Look for the puzzle piece icon (Extensions) in the toolbar
- Click the puzzle piece → find vibestack browse → click the pin icon
- Click the pinned icon in the toolbar
- The Side Panel opens on the right with a terminal running
claudePort: 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:
- Type
chrome://extensionsin the address bar- Look for the vibestack browse extension — it should be listed and enabled
- If it's there but not pinned, go back to any page, click the puzzle piece icon, and pin it
- 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 icon and enter port 34567 manually.
If C:
- Run
$B statusand show the output - If the server is not healthy, re-run Step 0 (probe, and ask before any replacement) and then Step 1 connect
- If the server IS healthy but the browser isn't visible, try
$B focus - 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='<BROWSE_BIN>'
$B goto https://github.com
Wait 2 seconds, then:
B='<BROWSE_BIN>'
$B snapshot -i
Tell the user: "Click debug in the Side Panel footer and open the
Activity tab — the goto and snapshot commands are listed there. Every
command Claude runs shows up in real time."
Step 5: The Side Panel terminal
Tell the user what the Side Panel holds:
The Side Panel runs a real Claude Code terminal (
claudein a PTY on this machine, working in the browser you see). Type to it like any terminal. If it shows "Claude Code not found", install theclaudeCLI and click "I installed it — try again". ↻ Restart starts a fresh session; the size picker next to it changes the text size.Buttons above the terminal act on the current page:
- Cleanup removes ads, cookie banners and pop-ups
- Screenshot captures the page
- Cookies opens the cookie picker to import a signed-in session from your own browser (the same flow as /setup-browser-cookies)
The debug toggle in the footer opens three more tabs: Activity (every browse command as it runs), Refs (the
@erefs from the last snapshot) and Inspector (pick an element to see its box model and CSS rules).
Step 6: What's next
Tell the user:
You're all set. With the connected browser you can:
- Run any vibestack skill (
/qa,/design-review,/benchmark) and watch every page load and click in the visible window; the Activity tab logs each command- Drive it directly:
$B goto <url>,$B click <sel>,$B fill <sel> <val>,$B snapshot -i$B focusbrings the window to the front;$B disconnectcloses it and returns to headless modeThe browser keeps its own profile, separate from your regular Chrome. Import a signed-in session with Cookies or /setup-browser-cookies when a test needs one.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |