agent-browser-loop 0.2.2 → 0.3.0

package/.claude/skills/agent-browser-loop/REFERENCE.md

@@ -1,5 +1,7 @@
 # Agent Browser Loop - CLI Reference
 
+<!-- TIP: Check package.json for dev server scripts to find the port to test (e.g. dev:basic, dev:next) -->
+
 Complete CLI reference for `agent-browser`.
 
 ## Commands
@@ -18,12 +20,19 @@ agent-browser open <url> [options]
 | `--headed` | Show browser window (default: headless) |
 | `--new, -n` | Create new session with auto-generated ID |
 | `--session, -s <id>` | Target session (from `--new`) |
+| `--profile, -p <name>` | Load profile and save back on close |
+| `--no-save` | Don't save profile changes on close (read-only) |
+| `--width, -W <pixels>` | Viewport width (default: 1280) |
+| `--height, -H <pixels>` | Viewport height (default: 720) |
 | `--json` | Output as JSON |
 
 **Examples:**
 ```bash
 agent-browser open http://localhost:3000
 agent-browser open http://localhost:3000 --headed
+agent-browser open http://localhost:3000 --width 1920 --height 1080
+agent-browser open http://localhost:3000 --profile admin  # Loads and auto-saves on close
+agent-browser open http://localhost:3000 --profile admin --no-save  # Read-only
 agent-browser open --new http://localhost:3000  # Output: Session: swift-fox
 ```
 
@@ -54,6 +63,7 @@ agent-browser act <actions...> [options]
 | Type | `type:<ref>:<text>` | `type:input_0:hello` |
 | Press key | `press:<key>` | `press:Enter` |
 | Scroll | `scroll:<direction>[:<amount>]` | `scroll:down:500` |
+| Resize | `resize:<width>:<height>` | `resize:1920:1080` |
 | Select | `select:<ref>:<value>` | `select:select_0:option1` |
 | Check | `check:<ref>` | `check:checkbox_0` |
 | Uncheck | `uncheck:<ref>` | `uncheck:checkbox_0` |
@@ -213,6 +223,127 @@ agent-browser screenshot
 
 ---
 
+### `resize <width> <height>`
+
+Resize the browser viewport mid-session.
+
+```bash
+agent-browser resize <width> <height> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--session, -s <id>` | Target session |
+| `--json` | Output as JSON |
+
+**Examples:**
+```bash
+agent-browser resize 1920 1080
+agent-browser resize 375 667  # Mobile viewport
+agent-browser act "resize:1920:1080"  # Via act command
+```
+
+---
+
+### `profile <subcommand>`
+
+Manage session storage profiles (cookies + localStorage). The `<name>` in all commands is an arbitrary identifier you choose (e.g., `admin`, `testuser`, `staging`).
+
+#### `profile list`
+
+List all available profiles.
+
+```bash
+agent-browser profile list [--json]
+```
+
+#### `profile show <name>`
+
+Show profile contents.
+
+```bash
+agent-browser profile show <name> [--json]
+```
+
+#### `profile save <name>`
+
+Save current session storage to a profile.
+
+```bash
+agent-browser profile save <name> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--session, -s <id>` | Source session |
+| `--global` | Save to global profiles (`~/.config/agent-browser/profiles/`) |
+| `--private` | Save to private profiles (gitignored) |
+| `--description, -d <text>` | Profile description |
+
+#### `profile delete <name>`
+
+Delete a profile.
+
+```bash
+agent-browser profile delete <name>
+```
+
+#### `profile import <name> <path>`
+
+Import profile from a Playwright storage state JSON file.
+
+```bash
+agent-browser profile import <name> <path> [--global] [--private]
+```
+
+#### `profile capture <name>`
+
+Opens a headed browser, lets you interact manually (log in, etc.), then saves the session when you press Enter in the terminal.
+
+```bash
+agent-browser profile capture <name> --url <url> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--url <url>` | URL to navigate to (required) |
+| `--global` | Save to global profiles |
+| `--private` | Save to private profiles |
+| `--description, -d <text>` | Profile description |
+
+**Examples:**
+```bash
+# Capture a session (opens browser, you log in, press Enter to save)
+agent-browser profile capture admin --url http://localhost:3000/login
+agent-browser profile capture testuser --url http://localhost:3000/login
+
+# Save from an already-open session instead
+agent-browser open http://localhost:3000/login --headed
+# ... log in manually ...
+agent-browser profile save admin --description "Admin account"
+
+# Use profile (loads saved cookies/localStorage)
+agent-browser open http://localhost:3000/dashboard --profile admin
+
+# List profiles
+agent-browser profile list
+
+# Import existing Playwright storage state file
+agent-browser profile import staging ./storage-state.json --global
+```
+
+**Profile Storage Locations:**
+- Local: `.agent-browser/profiles/<name>.json` (project-scoped, shareable via git)
+- Private: `.agent-browser/profiles/.private/<name>.json` (gitignored)
+- Global: `~/.config/agent-browser/profiles/<name>.json` (user-level)
+
+Resolution order: private -> local -> global
+
+---
+
 ### `close`
 
 Close browser session or stop daemon.

package/.claude/skills/agent-browser-loop/SKILL.md

@@ -3,12 +3,15 @@ name: agent-browser-loop
 description: Use when an agent must drive a live browser session in a back-and-forth loop (state -> explicit actions -> state) for UI validation, reproducible QA, or debugging UI behavior. Prefer this over one-shot CLI usage when an agent needs inspectable, stepwise control.
 ---
 
+
 # Agent Browser Loop
 
 Control a browser via CLI. Execute actions, read state, and verify UI changes in a stepwise loop.
 
 ## Quick Start
 
+> **TIP**: Check package.json for dev server scripts to find the port to test
+
 ```bash
 # Open a URL (starts browser daemon automatically)
 agent-browser open http://localhost:3000
@@ -165,13 +168,42 @@ agent-browser close
 # Headed mode (visible browser)
 agent-browser open http://localhost:3000 --headed
 
-# JSON output
-agent-browser state --json
+# Custom viewport size
+agent-browser open http://localhost:3000 --width 1920 --height 1080
+
+# Resize mid-session
+agent-browser resize 1920 1080
+```
+
+## Profiles (Session Storage)
+
+Save and reuse cookies/localStorage across sessions. The profile name (e.g., `admin`, `testuser`) is an arbitrary identifier you choose.
 
-# Skip state in response
-agent-browser act click:button_0 --no-state
+```bash
+# Capture: opens browser, you interact, press Enter in terminal to save
+agent-browser profile capture admin --url http://localhost:3000/login
+
+# Or save from an already-open session
+agent-browser open http://localhost:3000/login --headed
+# ... log in manually ...
+agent-browser profile save admin
+
+# Use saved profile - auto-saves updated tokens on close
+agent-browser open http://localhost:3000/dashboard --profile admin
+# ... use the app (tokens may refresh) ...
+agent-browser close  # Updated tokens saved back to profile
+
+# Use --no-save for read-only (don't save changes back)
+agent-browser open http://localhost:3000 --profile admin --no-save
+
+# List/manage profiles
+agent-browser profile list
+agent-browser profile show admin
+agent-browser profile delete admin
 ```
 
+Profiles are stored locally (`.agent-browser/profiles/`) or globally (`~/.config/agent-browser/profiles/`).
+
 ## Multi-Session
 
 Run multiple browsers in parallel with `--new`:

package/README.md

@@ -57,6 +57,45 @@ agent-browser state
 
 Every command returns the current page state - interactive elements, form values, scroll position, console errors, network failures. The agent sees exactly what it needs to verify the code works or debug why it doesn't.
 
+## Profiles (Session Storage)
+
+Save and reuse login sessions across runs:
+
+```bash
+# Save current session to a profile
+agent-browser profile save admin
+
+# Use profile (auto-saves updated tokens on close)
+agent-browser open http://localhost:3000 --profile admin
+
+# Use --no-save for read-only access
+agent-browser open http://localhost:3000 --profile admin --no-save
+
+# Other commands
+agent-browser profile list
+agent-browser profile capture admin --url http://localhost:3000/login
+agent-browser profile delete admin
+```
+
+Profiles store cookies and localStorage. Use `--global` for user-level profiles, `--private` for gitignored project profiles.
+
+## Multi-Session
+
+Run multiple browser sessions in parallel:
+
+```bash
+# Create sessions with auto-generated IDs
+agent-browser open --new http://localhost:3000     # Output: Session: swift-fox
+agent-browser open --new http://localhost:3000     # Output: Session: calm-river
+
+# Target specific sessions
+agent-browser act -s swift-fox click:button_0
+agent-browser state -s calm-river
+
+# List all sessions
+agent-browser sessions
+```
+
 ## CLI Reference
 
 | Command | Description |
@@ -102,23 +141,6 @@ agent-browser wait --timeout 60000         # Custom timeout
 --no-state            # Skip state in response
 ```
 
-## Multi-Session
-
-Run multiple browser sessions in parallel:
-
-```bash
-# Create sessions with auto-generated IDs
-agent-browser open --new http://localhost:3000     # Output: Session: swift-fox
-agent-browser open --new http://localhost:3000     # Output: Session: calm-river
-
-# Target specific sessions
-agent-browser act -s swift-fox click:button_0
-agent-browser state -s calm-river
-
-# List all sessions
-agent-browser sessions
-```
-
 ## State Output
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-browser-loop",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Let your AI coding agent drive a browser to verify its own work",
   "license": "MIT",
   "author": "Jason Silberman",

package/src/browser.ts

@@ -482,6 +482,28 @@ export class AgentBrowser {
     return actions.screenshot(this.getPage(), options);
   }
 
+  /**
+   * Resize the viewport
+   */
+  async resize(width: number, height: number): Promise<void> {
+    await this.getPage().setViewportSize({ width, height });
+    this.config.viewportWidth = width;
+    this.config.viewportHeight = height;
+  }
+
+  /**
+   * Get current viewport size
+   */
+  getViewportSize(): { width: number; height: number } {
+    const size = this.getPage().viewportSize();
+    return (
+      size ?? {
+        width: this.config.viewportWidth!,
+        height: this.config.viewportHeight!,
+      }
+    );
+  }
+
   /**
    * Get captured console logs
    */