Metadata-Version: 2.4
Name: navig-browser
Version: 0.1.0
Summary: Launch an isolated Chrome/Edge/Brave or Electron app, drive it over CDP, keep named profiles and stop only what it launched — the browser engine navig uses; runs on its own as `navig-browser`.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,automation,plugin,browser,cdp,chrome,playwright
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: navig-sdk>=2.15.0
Requires-Dist: navig-vault>=0.7.0
Requires-Dist: navig-generate>=0.2.1
Requires-Dist: psutil>=5.9.0
Requires-Dist: aiohttp<3.13.0,>=3.9.0; python_version >= "3.14"
Requires-Dist: aiohttp>=3.9.0; python_version < "3.14"
Requires-Dist: tldextract>=5.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Provides-Extra: drive
Requires-Dist: playwright>=1.40; extra == "drive"
Provides-Extra: stealth
Requires-Dist: patchright>=1.40; extra == "stealth"
Requires-Dist: browserforge>=1.2.0; extra == "stealth"
Provides-Extra: firefox
Requires-Dist: camoufox[geoip]>=0.4; extra == "firefox"

# navig-browser

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Launch an isolated Chrome/Edge/Brave or Electron app, drive it over CDP, keep named profiles and stop only what it launched — the browser engine navig uses; runs on its own as `navig-browser`.

**Works on its own** — its own CLI, no navig required · v0.1.0 · not on PyPI yet (install from source below)

**On its own** (no navig needed)

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-browser"
navig-browser --help   # no navig needed
```

**With navig**

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-browser"
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig cdp click` | Click by a11y ref or at coordinates. |
| `navig cdp detach` | Disconnect NAVIG's session but LEAVE the browser open (port stays on). |
| `navig cdp eval` | Evaluate JavaScript in the page (gated — JS can change page state). |
| `navig cdp inject` | Inject a persistent userscript (runs at document-start on every navigation). |
| `navig cdp key` | Press a key or key combination. |
| `navig cdp launch` | Launch an app with a debug port so CDP can attach. |
| `navig cdp launched` | List debug browsers NAVIG launched (and whether each is still live). |
| `navig cdp login` | Auto-login on the attached page from a vaulted website credential. |
| `navig cdp move` | Move the mouse to viewport coordinates. |
| `navig cdp nav` | Navigate a page to a URL (optionally choose which tab first). |
| `navig cdp new` | Open a COMPLETELY FRESH, isolated browser (own profile + own debug port). |
| `navig cdp open` | Open (or REUSE if already running) a named profile's browser on its stable port. |
| `navig cdp profile close` | Close a running profile's browser (leaves the profile registered). |
| `navig cdp profile export` | Export a profile's coherent persona (+ optional session) as a portable capsule. |
| `navig cdp profile import` | Import a persona capsule → (re)create the profile, its proxy, and its session. |
| `navig cdp profile list` | List named automation profiles (and optionally your real browser profiles). |
| `navig cdp profile new` | Create a named browser profile (a fresh automation profile by default). |
| `navig cdp profile open` | Open (or reuse) a profile — same as `navig cdp open <name>`. |
| `navig cdp profile proxy` | Assign a per-profile proxy (overrides the shared browser.proxies pool). |
| `navig cdp profile prune` | Reclaim disk from browser profiles (throwaway sessions, or a profile you name). |
| `navig cdp profile remove` | Remove a profile from the registry (closing it first). |
| `navig cdp profile usage` | Show how much disk each browser profile is using. |
| `navig cdp profile use` | Set the active profile (navig do / cdp default to it). |
| `navig cdp profile vacuum` | Reclaim disk from a profile WITHOUT losing its logins: delete only what Chrome rebuilds. |
| `navig cdp record` | Record the attached page to an mp4 (screencast → video). |
| `navig cdp screenshot` | Capture a screenshot of the attached page. |
| `navig cdp scroll` | Scroll the page by a wheel delta (positive = down). |
| `navig cdp snapshot` | Accessibility snapshot with numeric refs (feed to `cdp click --ref`). |
| `navig cdp status` | Show the platform, launchable apps, live CDP targets, and any LEAKED browsers. |
| `navig cdp stop` | Close a NAVIG-launched debug browser (turns the debug port OFF). |
| `navig cdp switch` | Make a specific open tab the active target (agent/daemon sessions). |
| `navig cdp tabs` | List EVERY open page in the browser (full inventory from raw CDP). |
| `navig cdp targets` | List live CDP endpoints on localhost. |
| `navig cdp type` | Type text into the focused element. |

</details>

<!-- navig:plugin-card:end -->

NAVIG **Browser** — launch an isolated Chrome, Edge, Brave or Electron app with a debug port,
drive it over CDP, keep named profiles per project or account, and stop **only** the browsers
it launched. It is the browser engine navig itself uses, and it runs on its own as
`navig-browser`.

## On its own

```bash
pip install "navig-browser[drive]"          # [drive] adds Playwright's CDP client for nav/eval/click…
navig-browser new                           # a fresh, isolated browser; prints its port
navig-browser nav https://example.com -p <port>
navig-browser eval "document.title" -p <port> -y
navig-browser screenshot -o shot.png -p <port>
navig-browser profile new work              # a named profile on a stable port
navig-browser stop --port <port>            # or --all: only browsers navig-browser launched
```

It uses your installed Chrome/Edge/Brave — no bundled browser download. Launch records,
profiles and the signer cache live in navig's config folder (`~/.navig`, or `NAVIG_CONFIG_DIR`),
so they are the same ones navig sees after you install it. `login` fills a saved website login
from the shared encrypted vault (`navig-vault`). Stealth Chromium and Camoufox are extras:
`pip install "navig-browser[stealth]"` / `"navig-browser[firefox]"`.

**Never leaves a browser behind.** Every browser it starts is recorded with its real PID and
start time; `stop` closes only a recorded browser that is still the same process (a recycled
PID is never killed), and never touches a browser you opened yourself.

## Inside navig

The same commands are `navig cdp …`. navig also drives this engine from `navig do`, `navig
gmail`, `navig links`, `navig cortex`, the MCP `cdp_*` tools and the agent's browser tool;
`navig.browser.<module>` is an identity alias of `navig_browser.<module>`. `navig cortex`
(the AI page-driving loop) needs navig's AI.
