# 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
```

The PyPI package is useful when you want the CLI or Python API outside the desktop bundle, but it still must run on the same machine as the Nowledge Mem app and the connected browser extension.

### 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 on the same machine (provides the local browser bridge)

## 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
```

## Local-only security model

`browse-now` talks to the browser bridge endpoints exposed by the Nowledge Mem app. Those endpoints are intentionally **local-only**. They are **not** exposed through Access Anywhere, Cloudflare tunnels, or other remote-access paths.

What this means in practice:

- `browse-now` must run on the same machine as the Nowledge Mem app
- the controlled browser must also be on that same machine with the Exchange extension active
- publishing to PyPI makes the CLI and Python API easier to install, but does **not** turn browser automation into a remote-access surface

`NOWLEDGE_API_URL` and `NOWLEDGE_API_KEY` can still point at another local deployment shape, but they are not a supported way to tunnel browser automation through Access Anywhere.

## 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 (most reliable targeting) |
| `click -T "text"` | 85% | Fallback for dialogs/menus |

**Important clarification:**

- High reliability means the CLI can target/click the intended element.
- It does **not** bypass login, paywalls, tokenized links, or anti-bot restrictions.
- For gated sites (social media, banking, etc.), always validate navigation using `browse-now get url` / `browse-now get title` after clicks.

**Decision tree:**

1. `snapshot -i` → Found ref? → `click @eN`
2. After click/fill: `wait 1-2` → `get url` (detect redirect/404/login wall)
3. Sparse results? → Use screenshot + `click -T "visible text"`
4. 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 on the same machine as `browse-now`
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)
