chaining (#497)

README.md

@@ -543,6 +543,23 @@ agent-browser fill @e3 "input text"
 agent-browser snapshot -i --json
 ```
 
+### Command Chaining
+
+Commands can be chained with `&&` in a single shell invocation. The browser persists via a background daemon, so chaining is safe and more efficient:
+
+```bash
+# Open, wait for load, and snapshot in one call
+agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+
+# Chain multiple interactions
+agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
+
+# Navigate and screenshot
+agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
+```
+
+Use `&&` when you don't need intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs before interacting).
+
 ## Headed Mode
 
 Show the browser window for debugging:

cli/src/output.rs

@@ -2000,6 +2000,13 @@ Examples:
   agent-browser --profile ~/.myapp open example.com    # Persistent profile
   agent-browser --session-name myapp open example.com  # Auto-save/restore state
 
+Command Chaining:
+  Chain commands with && in a single shell call (browser persists via daemon):
+
+  agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+  agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
+  agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
+
 iOS Simulator (requires Xcode and Appium):
   agent-browser -p ios open example.com                    # Use default iPhone
   agent-browser -p ios --device "iPhone 15 Pro" open url   # Specific device

docs/src/app/commands/page.mdx

@@ -242,6 +242,18 @@ agent-browser reload                  # Reload page
 --debug                  # Debug output
 ```
 
+## Command chaining
+
+Chain commands with `&&` in a single shell invocation. The browser persists via a background daemon, so chaining works naturally and is more efficient than separate calls:
+
+```bash
+agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
+agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
+```
+
+Use `&&` when you don't need to read intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact with those refs).
+
 ## Local files
 
 Open local files (PDFs, HTML) using `file://` URLs:

docs/src/app/quick-start/page.mdx

@@ -63,6 +63,23 @@ agent-browser wait --url "**/dashboard"  # Wait for URL pattern
 agent-browser wait 2000                  # Wait milliseconds
 ```
 
+## Command chaining
+
+Chain commands with `&&` in a single shell call. The browser persists via a background daemon, so chaining is safe and efficient:
+
+```bash
+# Open, wait, and snapshot in one call
+agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+
+# Chain multiple interactions
+agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
+
+# Navigate and capture
+agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
+```
+
+Use `&&` when you don't need intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs before interacting).
+
 ## JSON output
 
 For programmatic parsing in scripts:

skills/agent-browser/SKILL.md

@@ -27,6 +27,23 @@ agent-browser wait --load networkidle
 agent-browser snapshot -i  # Check result
 ```
 
+## Command Chaining
+
+Commands can be chained with `&&` in a single shell invocation. The browser persists between commands via a background daemon, so chaining is safe and more efficient than separate calls.
+
+```bash
+# Chain open + wait + snapshot in one call
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+
+# Chain multiple interactions
+agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3
+
+# Navigate and capture
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
+```
+
+**When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding (e.g., open + wait + screenshot). Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact using those refs).
+
 ## Essential Commands
 
 ```bash