qqbrowser-use

QQBrowserUse

Browser automation CLI for AI agents. Wraps every task in an isolated Chrome Tab Group, supports both live automation and reusable playbook replay.

Platform Support

Linux x86_64, Windows, macOS. Other Linux architectures (ARM, etc.) are not supported.

Installation

# Linux / macOS
pipx install qqbrowser-skill
qqbrowser-skill install   # Download and install QQ Browser

# Windows
pip install qqbrowser-skill
qqbrowser-skill install

Reference Files (Load On Demand)

This main file is a decision guide. Load the following references only when they apply:

---

Key Concepts

• Element Index: Encoded string like 2_sfli_qp0u (highlightIndex_attrHash_xpathHash). Generated by browser_snapshot, used to target elements. Indices are regenerated on every snapshot — always re-snapshot before reusing indices; using a stale index will fail or target the wrong element. Never invent numeric indices like 1 or 2; always copy the encoded index exactly from the latest browser_snapshot output.
• Snapshot: Returns page content with indexed elements. Re-snapshot after any DOM change (navigation, form submit, modal, AJAX). Standalone browser_snapshot calls consume tokens — avoid unnecessary ones.
• Session: AI tasks MUST be wrapped with browser_start_session / browser_end_session for tab group isolation. Details: references/session-lifecycle.md.
• Task Recording: Manual browser tasks intended for replay MUST be wrapped with task_begin / task_end for playbook generation. Details: references/playbook.md.
• Playbook: Parameterized JSON script that replays a recorded task without AI. Details: references/playbook.md.

---

⚠️ Core Workflow (MANDATORY)

Every automation MUST be wrapped in browser_start_session / browser_end_session, and you MUST run playbook_list before any task_begin or browser_go_to_url. Never start manual automation without first checking for existing playbooks.

Decision Flow

Step 0: Composite request?                    ← Multi-domain / cross-site data flow?
        ├── YES → See references/session-lifecycle.md → Handling Composite Tasks.
        │         Start ONE session for the whole composite task,
        │         then run each sub-task through Step 2-3 independently,
        │         and call browser_end_session once after all sub-tasks.
        └── NO  → Continue as a single task ↓

Step 1: browser_start_session                 ← REQUIRED, first command
Step 2: playbook_list                         ← REQUIRED, decide branch
Step 3: Match?
        ├── YES → browser_replay              ← Branch A: Replay
        └── NO  → Manual automation
                  ├── Recording mode          ← Branch B: user explicitly asks to record
                  │     task_begin
                  │     browser_* operations...
                  │     task_end
                  │     → then continue with references/playbook.md
                  └── Non-recording mode      ← Branch C: one-off task
                        browser_* operations...
Step 4: browser_end_session                   ← REQUIRED, always executed

Recording (Branch B) triggers only on explicit user request. Trigger words: "record this", "save this", "make reusable", "保存为脚本", "录一下", "下次还要用". Without an explicit request, use Branch C (non-recording) — do not wrap the operations in task_begin / task_end.

Step 1: Start Session (REQUIRED)

qqbrowser-skill browser_start_session --sessionId task--

sessionId must be unique per task (e.g. task-form-001). Full flags and idempotency rules: references/session-lifecycle.md.

Step 2: Check Playbooks (REQUIRED — DO NOT SKIP)

qqbrowser-skill playbook_list

Match returned playbooks against the user's task by name, description, keywords, and target URL. Even a partial match is enough to prefer replay over manual work.

Step 3: Branch by Match Result

Branch A — Playbook matched → Replay

⚠️ browser_replay may run for up to 10 minutes. Wait for it to return — NEVER interrupt, retry, or fall back to manual mode while it is still running. Replayed operations are usually not idempotent (posting, submitting, messaging), so a premature retry will cause duplicate side effects.

qqbrowser-skill browser_replay --script  --variables '{...}'

Output format and how to consume step_results: references/commands.md → browser_replay Output Format.

Branch B — No playbook + user asked to record → Manual with recording

Before calling task_begin, MUST read references/playbook.md. These rules are required to make the recording reusable; do not start recording from the short example alone.

Wrap operations in task_begin / task_end so a playbook can be generated afterwards.

qqbrowser-skill task_begin --description "描述任务"
qqbrowser-skill browser_go_to_url --url 
qqbrowser-skill browser_snapshot                    # Get element indices (AI use only; filtered on replay)
# ... interact using indices ...
qqbrowser-skill browser_snapshot                    # Re-snapshot after DOM changes
qqbrowser-skill task_end

Recording quality rules (mandatory inside task_begin/task_end): references/playbook.md.

After task_end, raw recordings are NOT replay-ready. Continue following references/playbook.md to load task_latest, generate the playbook JSON, save it, and verify it safely.

Branch C — No playbook + no recording request → Plain manual

Default fallback for one-off tasks. Do not call task_begin / task_end.

qqbrowser-skill browser_go_to_url --url 
qqbrowser-skill browser_snapshot
# ... interact using indices ...

Step 4: End Session (REQUIRED — always executed)

Always call browser_end_session at the end, regardless of which branch was taken and regardless of success or failure:

qqbrowser-skill browser_end_session --sessionId task--

---

Common Patterns

Every example below is a complete task lifecycle template — it starts with browser_start_session, checks playbook_list, then ends with browser_end_session. AI agents must include all three calls in real runs; do not strip them when adapting these snippets. Replace placeholder URLs and indices with live values from the current task.

Form Submission (Branch C)

qqbrowser-skill browser_start_session --sessionId task-form-001
qqbrowser-skill playbook_list                       # REQUIRED before manual work
qqbrowser-skill browser_go_to_url --url https://example.com/signup
qqbrowser-skill browser_snapshot
# Copy encoded indices from the latest browser_snapshot, e.g. "2_sfli_qp0u". Never invent numeric indices.
qqbrowser-skill browser_input_text --index "" --text "Jane Doe"
qqbrowser-skill browser_input_text --index "" --text "jane@example.com"
qqbrowser-skill browser_select_dropdown_option --index "" --text "California"
qqbrowser-skill browser_check_op --index "" --value
qqbrowser-skill browser_click_element --index ""
qqbrowser-skill browser_wait --seconds 2
qqbrowser-skill browser_snapshot                    # Verify result
qqbrowser-skill browser_end_session --sessionId task-form-001

Data Extraction

Pick the right approach based on how the output will be consumed:

Full decision matrix: references/commands.md → browser_snapshot --markdown Usage Guide.

Structured extraction example (Branch C):

qqbrowser-skill browser_start_session --sessionId task-extract-001
qqbrowser-skill playbook_list
qqbrowser-skill browser_go_to_url --url https://example.com/products
qqbrowser-skill browser_eval_content_js --script "JSON.stringify(Array.from(document.querySelectorAll('.product-item')).slice(0,10).map(el=>({name:el.querySelector('.name')?.textContent?.trim(), price:el.querySelector('.price')?.textContent?.trim()})))"
qqbrowser-skill browser_end_session --sessionId task-extract-001

Infinite Scroll Pages

qqbrowser-skill browser_start_session --sessionId task-feed-001
qqbrowser-skill playbook_list
qqbrowser-skill browser_go_to_url --url https://example.com/feed
qqbrowser-skill browser_scroll_to_bottom            # Trigger lazy loading
qqbrowser-skill browser_wait --seconds 2            # Wait for content
qqbrowser-skill browser_snapshot                    # Get updated content
qqbrowser-skill browser_end_session --sessionId task-feed-001

---

Evaluation Report

See the full skill evaluation report: QQBrowserSkillReport