# browse-now

Browser automation CLI for AI agents. Control your browser from the command line with reliable element targeting through accessibility tree refs.

**Part of [Nowledge Mem](https://mem.nowledge.co)** - Personal memory for AI agents.

## Why browse-now?

- **Low overhead**: No tool definitions loaded into LLM context (unlike MCP)
- **Reliable targeting**: Uses accessibility tree refs (`@e1`, `@e2`) for 95%+ click reliability
- **AI-agent optimized**: Designed for the `snapshot → click → repeat` workflow
- **Multi-browser support**: Works with Chrome, Arc, Edge, and other Chromium browsers

## Installation

```bash
pip install browse-now
```

### Prerequisites

1. **[Nowledge Memory Exchange](https://chromewebstore.google.com/detail/nowledge-memory-exchange/kjgpkgodplgakbeanoifnlpkphemcbmh)** Chrome extension (verson v2.0.71 or later) installed
2. **[Nowledge Mem](https://mem.nowledge.co)** app running (provides the bridge server)

## Quick Start

```bash
# Navigate to a page
browse-now open https://example.com

# Get interactive elements with refs
browse-now snapshot -i
# Output:
#   textbox "Search" [e1]
#   button "Submit" [e2]
#   link "About" [e3]

# Click by ref
browse-now click @e2

# Fill input
browse-now fill @e1 "AI agents" --submit
```

## Core Workflow

The browse-now workflow matches the Claude Chrome Extension pattern:

```
1. browse-now open <url>           # Open page (isolated agent tab)
2. browse-now snapshot -i          # Get refs [e1], [e2]...
3. browse-now click @e5            # Click by ref
4. browse-now fill @e3 "text"      # Fill by ref
5. (If page changed) → snapshot -i again
```

## Command Reference

### Navigation

```bash
browse-now open <url>              # Navigate (isolated tab by default)
browse-now open <url> --no-isolated  # Use current active tab
browse-now back                    # Go back
browse-now forward                 # Go forward
browse-now reload                  # Reload page
```

### Snapshot (Page Analysis)

```bash
browse-now snapshot                # Full accessibility tree
browse-now snapshot -i             # Interactive elements only (recommended)
browse-now snapshot -i -w 1000     # Wait 1s for late-loading content
browse-now snapshot -s "main"      # Scope to CSS selector
```

### Interactions

```bash
# Click by ref (95%+ reliable - primary method)
browse-now click @e1

# Click by text (85% reliable - fallback for dialogs)
browse-now click -T "Submit"
browse-now click -T "确认"         # Works with Chinese

# Fill and type
browse-now fill @e2 "text"         # Clear and type
browse-now fill @e2 "text" --submit  # Fill and submit
browse-now type @e2 "more"         # Append without clearing

# Other interactions
browse-now press Enter             # Press keyboard key
browse-now hover @e1               # Hover (reveal hidden UI)
browse-now scroll down 500         # Scroll page
```

### Get Information

```bash
browse-now get text @e1            # Get element text
browse-now get title               # Get page title
browse-now get url                 # Get current URL
browse-now get page-text           # Extract full page text
```

### Screenshots

```bash
browse-now screenshot page.png     # Save to file
browse-now screenshot --full       # Full page screenshot
browse-now screenshot -e @e1       # Element screenshot
```

### Wait

```bash
browse-now wait @e1                # Wait for element
browse-now wait 2                  # Wait 2 seconds
browse-now wait 500ms              # Wait 500 milliseconds
```

### Tabs

```bash
browse-now tabs                    # List open tabs
browse-now switch <tab_id>         # Switch to tab by ID
browse-now agent-tab status        # Check agent tab status
```

### Multi-Browser

```bash
browse-now browsers                # List connected browsers
browse-now -b arc_123 open <url>   # Target specific browser
```

## JSON Output

For programmatic use, add `-j` or `--json`:

```bash
browse-now -j snapshot -i
browse-now -j click @e1
browse-now -j get title
```

## Python API

```python
from browse_now import BrowserClient

async def main():
    async with BrowserClient() as browser:
        await browser.navigate("https://example.com")
        await browser.click("#login-btn")
        await browser.fill("#email", "user@example.com")
        await browser.fill("#password", "secret", submit=True)

import asyncio
asyncio.run(main())
```

### Sync API

```python
from browse_now import BrowserClientSync

browser = BrowserClientSync()
browser.navigate("https://example.com")
browser.click("#btn")
```

## Reliability Guide

| Method | Reliability | Use Case |
|--------|-------------|----------|
| `click @eN` | 95%+ | Primary method |
| `click -T "text"` | 85% | Fallback for dialogs/menus |

**Decision tree:**

1. `snapshot -i` → Found ref? → `click @eN`
2. Sparse results? → Use screenshot + `click -T "visible text"`
3. Re-snapshot with `-w 1000` if content loads late

## Example: Weibo Delete Flow

```bash
browse-now snapshot -i             # Find "更多" [e45]
browse-now click @e45              # Open menu
browse-now snapshot -i             # Find "删除" [e67]
browse-now click @e67              # Delete
browse-now snapshot -i             # Find "确定" [e89]
browse-now click @e89              # Confirm
```

## Troubleshooting

1. **No browser connected**: Make sure the [Nowledge Memory Exchange extension](https://chromewebstore.google.com/detail/nowledge-memory-exchange/kjgpkgodplgakbeanoifnlpkphemcbmh) is installed and active
2. **Connection refused**: Ensure [Nowledge Mem](https://mem.nowledge.co) is running
3. **Element not found**: Run `snapshot -i` again after page changes
4. **Sparse results**: Site may have poor accessibility. Use `screenshot` + `click -T "visible text"`
5. **Multiple browsers**: Use `-b <browser_id>` to target specific browser

## Documentation

- [Full Documentation](https://mem.nowledge.co/docs/)
- [Nowledge Mem](https://mem.nowledge.co) - Personal memory for AI agents
- [Chrome Extension](https://chromewebstore.google.com/detail/nowledge-memory-exchange/kjgpkgodplgakbeanoifnlpkphemcbmh)

## Acknowledgments

Inspired by [Claude Chrome Extension](https://chromewebstore.google.com/detail/claude/hbinfpnnfjflmkhgpmaenfniiaihgokd) and [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) for the browser automation approach.

## License

Proprietary - see [Nowledge Terms of Service](https://nowledge.co/terms)
