/browser-work

name: browser-work
description: |
  Recon-first browser automation. Orchestrator explores the site first via chromux,
  saves a guide file with insights, then delegates execution to browser-explorer agent.
  Use when: "/browser-work", "브라우저 작업", "사이트에서 해줘", "웹에서 해줘",
  "LinkedIn에서", "크롬으로", "browser task", "automate this site".
version: 1.0.0

Browser Work

Recon-first browser automation: explore → document → delegate.

Purpose

To reliably execute browser tasks on the user's behalf, the orchestrator first scouts the site directly, creates a pitfall-prevention guide, then delegates execution to the browser-explorer agent.

Runtime Surface

Claude Code

• Use hook-provided `CLAUDE_SESSION_ID` for `~/.hoyeon/{session}/` paths.
• Delegate with the logical browser agent described below.

Codex

• Use Bash-first chromux operations. Do not add Hoyeon MCP for v1.
• If no hook-provided session ID exists, generate one with

`date +%Y%m%d-%H%M%S` and store guides under `$HOME/.hoyeon/codex-browser-$RUN_ID/`.

• Map the logical browser agent to the Codex adapter

`hoyeon-browser-explorer` when installed.

• If the current Codex session has not loaded that adapter, complete the

smallest safe browser pass directly with chromux and report the fallback.

• Use the Browser Use plugin only when the user explicitly asks for Codex

in-app browser behavior; this skill's canonical browser runtime is chromux.

Why Recon First?

When an agent sees a site for the first time, there's a lot of trial and error (snapshot vs. screenshot confusion, clicking wrong elements, unfamiliar site structure). If the orchestrator walks through one cycle first and builds a "map," the agent can execute accurately.

Execution

Step 0: Setup

0-1. Session Init

SESSION_ID="[CLAUDE_SESSION_ID from UserPromptSubmit hook]"
WORK_DIR="$HOME/.hoyeon/$SESSION_ID"
mkdir -p "$WORK_DIR"
echo "WORK_DIR=$WORK_DIR"

0-2. Chromux Check

Resolve chromux path. **Remember the output literally** — you'll inline it in every command.

CX=$(command -v chromux 2>/dev/null || echo "") && [ -n "$CX" ] && echo "CHROMUX=$CX" || (npx @team-attention/chromux help >/dev/null 2>&1 && echo "CHROMUX=npx @team-attention/chromux" || echo "MISSING")

If `MISSING`, report error and stop.

Launch Chrome in headless mode (no visible window, but fully functional):

/path/to/chromux launch default --headless 2>/dev/null || true

To let the user see a live tab (e.g., during recon or debugging), use `show` — no restart needed:

/path/to/chromux show exp-ab12   # Opens DevTools in user's browser

0-3. Generate Session ID

openssl rand -hex 2

Remember the output (e.g., `ab12`) → your chromux session ID is `exp-ab12`. Inline it literally in every command.

Step 1: Assess Complexity

Before doing recon, assess whether the task needs it:

| Complexity | Criteria | Action | |------------|----------|--------| | **Simple** | Single page, 1-2 clicks, well-known site (Google, GitHub) | Skip recon → go directly to Step 4 (Delegate) | | **Medium** | Multi-step workflow, unfamiliar site, 3+ interactions | Do recon (Step 2-3) | | **Complex** | Dynamic content, auth flows, pagination, bot-sensitive site | Do thorough recon (Step 2-3) + extra caution notes |

If skipping recon, still create a minimal guide file with the task description and URL.

Step 2: Recon (Orchestrator explores directly)

**You (the orchestrator) use chromux directly.** Follow the chromux guide in `references/chromux-guide.md`.

2-1. Navigate & Snapshot

/path/to/chromux open exp-ab12 "<target-url>" && sleep 2 && /path/to/chromux snapshot exp-ab12

2-2. Walk Through the Workflow

Execute the **entire workflow once** — the same steps the agent will need to do:

1. **Snapshot** the page → identify key elements and their @ref numbers 2. **Click/interact** as needed → observe what changes 3. **Snapshot again** after each action → note how @ref numbers shift 4. **Note obstacles**: popups, modals, login walls, infinite scroll, dynamic loading 5. **Note patterns**: does "load more" change @ref numbers? Are there confirmation dialogs?

**Bot detection caution**:

• Add `wait 2000` between actions (don't click rapidly)
• Don't repeat the same action more than 3 times quickly
• If you see a CAPTCHA or rate limit warning, stop and note it in the guide

2-3. Close Recon Session

/path/to/chromux close exp-ab12

Step 3: Write Guide File

Save recon findings to `$WORK_DIR/guide.md`. This is the "map" the agent will follow.

cat > "$WORK_DIR/guide.md" << 'GUIDE_EOF'
# Browser Work Guide

## Task
[What the user wants done — 1-2 sentences]

## Target URL
[Starting URL]

## Site Characteristics
- [Login required? Already logged in?]
- [Single page or multi-page workflow?]
- [Dynamic content loading? (infinite scroll, AJAX)]
- [Known bot detection? Rate limits?]

## Workflow Steps
1. [Step description] — [which element to look for in snapshot]
2. [Step description] — [expected @ref pattern or text to search for]
3. ...

## Pitfalls & Insights
- [Things that could trip up the agent]
- [e.g., "Sort dropdown is NOT the first artdeco-dropdown — look for text 'Most Relevant'"]
- [e.g., "'Load more' button changes @ref every time — always re-snapshot"]
- [e.g., "Confirmation modal appears after clicking Connect — look for 'Send without a note'"]

## Bot Detection Notes
- [Recommended delay between actions]
- [Any rate limits observed]
- [Pages to avoid rapid-fire clicking on]
GUIDE_EOF

**Fill in the template** with actual findings from your recon. Be specific — the agent will read this literally.

Step 4: Delegate to Browser-Explorer Agent

Launch the browser-explorer agent with the guide file content included in the prompt.

Agent(
  subagent_type: "hoyeon:browser-explorer",
  mode: "dontAsk",
  prompt: """
[Task description from user]

## Recon Guide

[Past