Metadata-Version: 2.4
Name: camoufox-browser
Version: 0.1.1
Summary: CLI-first browser automation powered by Camoufox, with optional MCP support.
Project-URL: Homepage, https://github.com/rlgrpe/camoufox-browser-cli
Project-URL: Repository, https://github.com/rlgrpe/camoufox-browser-cli
Project-URL: Issues, https://github.com/rlgrpe/camoufox-browser-cli/issues
Author: rlgrpe
License: MIT
License-File: LICENSE
Keywords: anti-detection,automation,browser,camoufox,cli,mcp,playwright
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: click>=8.0.0
Requires-Dist: cloverlabs-camoufox[geoip]>=0.5.5
Requires-Dist: pydantic>=2.0.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Camoufox Browser CLI

CLI-first browser automation powered by [Camoufox](https://github.com/CloverLabsAI/camoufox), with optional MCP support.

Host support for `camoufox-browser`: Linux and macOS only.

The project supports three user-facing workflows:

- `camoufox-browser`: the primary CLI for humans and agents
- `camoufox-mcp`: an optional MCP server that wraps the same command layer
- `skills/camoufox/SKILL.md`: a repo skill installed through `npx skills`

## Features

- Shared browser operation layer for CLI and MCP
- Persistent browser session through a lightweight background daemon
- Accessibility snapshot refs for agent-friendly interaction
- Anti-detection launch via Camoufox
- Tabs, screenshots, console/network inspection, uploads, dialogs, and form automation

## Installation

### CLI only

```bash
pip install camoufox-browser
# or
pipx install camoufox-browser
# or
uv tool install camoufox-browser
```

### CLI + MCP

```bash
pip install "camoufox-browser[mcp]"
# or
uv tool install "camoufox-browser[mcp]"
```

### From source

```bash
git clone https://github.com/rlgrpe/camoufox-browser-cli.git
cd camoufox-browser-cli

uv sync
uv run camoufox-browser --help
```

### Install browser binary

After installing the package, download the Camoufox browser binary:

```bash
camoufox-browser install
# or directly:
python -m camoufox fetch
uvx camoufox fetch
```

#### Linux system dependencies

```bash
# Ubuntu/Debian
sudo apt install -y libgtk-3-0 libx11-xcb1 libasound2

# Arch
sudo pacman -S gtk3 libx11 libxcb cairo libasound alsa-lib
```

## CLI Usage

The primary UX is similar to `agent-browser`: call the CLI directly and let it
start its background daemon automatically when needed.

```bash
camoufox-browser open https://example.com
camoufox-browser snapshot
camoufox-browser click 'button:Sign in'
camoufox-browser fill 'textbox:Email' me@example.com --submit
camoufox-browser screenshot --output page.png
camoufox-browser close
```

Run `camoufox-browser --help` for the full command surface.

### Core commands

| Command | Description |
|---------|-------------|
| `camoufox-browser open <url>` | Navigate to URL |
| `camoufox-browser snapshot` | Print accessibility tree with refs |
| `camoufox-browser click <ref>` | Click an element |
| `camoufox-browser fill <ref> <text>` | Fill or type into an element |
| `camoufox-browser select <ref> <value> [more-values...]` | Select dropdown value(s) |
| `camoufox-browser upload <ref> <file> [more-files...]` | Upload file(s) to a file input |
| `camoufox-browser drag <start-ref> <end-ref>` | Drag and drop |
| `camoufox-browser press <key>` | Press keyboard key |
| `camoufox-browser screenshot [--output FILE] [--full-page] [--ref REF]` | Take screenshot |
| `camoufox-browser eval '<js>'` | Run JavaScript on page |
| `camoufox-browser wait [--text TEXT] [--text-gone TEXT] [--time N]` | Wait for condition |
| `camoufox-browser close` | Close browser (daemon stays running) |

### Session and inspection

| Command | Description |
|---------|-------------|
| `camoufox-browser console [--level error\|warning\|info\|debug]` | Browser console output |
| `camoufox-browser network [--all]` | Recorded network requests |
| `camoufox-browser resize <width> <height>` | Resize viewport |
| `camoufox-browser tabs list\|new\|close [index]\|select <index>` | Manage tabs |
| `camoufox-browser dialog accept\|dismiss [prompt_text]` | Handle pending dialog |
| `camoufox-browser fill-form '<json-array>'` | Fill multiple fields from JSON |

### Advanced daemon control

These commands are optional. The normal workflow does not require them.

| Command | Description |
|---------|-------------|
| `camoufox-browser start [--headless] [--os windows\|macos\|linux] [--proxy PROXY]` | Start daemon explicitly |
| `camoufox-browser stop` | Stop daemon |
| `camoufox-browser status` | Check if daemon is running |
### Element refs

`camoufox-browser snapshot` prints an accessibility tree. Interactive elements
include a `[ref=...]` label:

```text
button "Sign in" [ref=button:Sign in]
textbox "Email" [ref=textbox:Email]
link "Forgot password?" [ref=link:Forgot password?]
```

Pass the ref value to interaction commands:

```bash
camoufox-browser click 'button:Sign in'
camoufox-browser fill 'textbox:Email' me@example.com
```

## MCP Server

Install the optional MCP extra:

```bash
pip install "camoufox-browser[mcp]"
```

The MCP server is a thin wrapper over the same operation layer used by
`camoufox-browser`.

### Add to Claude Code

```bash
claude mcp add camoufox-mcp -- uvx --from "camoufox-browser[mcp]" camoufox-mcp
```

### Claude Desktop configuration

```json
{
  "mcpServers": {
    "camoufox-mcp": {
      "command": "uvx",
      "args": ["--from", "camoufox-browser[mcp]", "camoufox-mcp"]
    }
  }
}
```

### From source

```json
{
  "mcpServers": {
    "camoufox-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--extra", "mcp",
        "--directory", "/path/to/camoufox-browser-cli",
        "camoufox-mcp"
      ]
    }
  }
}
```

## Skill Usage

The skill does not introduce a separate runtime. It teaches the agent to use
`camoufox-browser`, and it should be installed through `npx skills`.

```bash
npx skills add https://github.com/rlgrpe/camoufox-browser-cli --skill camoufox
```

Project-local install for specific agents:

```bash
npx skills add https://github.com/rlgrpe/camoufox-browser-cli --skill camoufox -a claude-code -a codex
```

## Development

```bash
uv sync
uv run python -m unittest
uv run python -m compileall camoufox_mcp
uv build --wheel
```

## Related Projects

- [Camoufox](https://github.com/CloverLabsAI/camoufox)
- [MCP](https://modelcontextprotocol.io/)
- [FastMCP](https://github.com/jlowin/fastmcp)
- [agent-browser](https://github.com/vercel-labs/agent-browser)
