octop-browser

📌 Overview

Octop Browser is a lightweight browser-use style tool that makes an agent's browser usage more accurate and reliable. Unlike typical stacks that route every action through Playwright, it launches a real Chromium and talks to the Chrome DevTools Protocol (CDP) directly — removing the intermediate layer so element targeting is driven by stable, live DOM refs and rarely misses.

Under the hood it starts a Chromium process with a --remote-debugging-port and speaks CDP itself. Because element references come straight from the live page, the agent acts on the real nodes, and those refs stay valid through reflows and re-renders — the result is higher action accuracy and lower token usage, with a persistent profile so logins don't expire mid-task.

Octop Browser's design goal: give an agent a browser it can act on with confidence — accurate clicks, low token cost, and persistent logins — through a small, well-shaped set of tools and a matching CLI.

Note: the install-browser command may bootstrap Playwright once purely to download a Chromium binary. Playwright is not a runtime dependency — the agent always drives the browser over CDP.

✨ Highlights

🧠 Core Technology

🤔 Features

Browser tools

browser_tool(action=...) exposes the following actions:

CDP session

• BrowserSession.create(profile=...) opens a persistent Chromium session.
• Stateless helper: browser_tool(action="navigate", url=..., profile="work").
• Set BROWSER_USE_IDLE_TIMEOUT_MINUTES to stop a local Chrome profile after that many minutes without real CDP activity (0, the default, disables it).
• await session.close(kill=True) or browser_tool(action="close_session", profile="work", kill=True) stops the local Chrome process immediately. Profile data and login state stay on disk.

CLI

Every tool is also a CLI command:

octop-browser install-browser     # fetch a Chromium binary (one-time)
octop-browser navigate "https://example.com" --profile work
octop-browser dom-tree --profile work
octop-browser click --ref inp_1 --profile work
octop-browser type "octop" --ref inp_1 --profile work
octop-browser screenshot --profile work
octop-browser close-session --kill --profile work   # also stop Chrome
# session: open / close-session / new-tab / switch-tab / close-tab / list-tabs

Record & replay

Octop Browser can record a real browsing session and replay it:

1. octop-browser record daemon-start — launch the long-lived recording daemon.
2. octop-browser record start — begin capturing the active tab.
3. Browse normally. A small injected script captures clicks, typed text, navigations, and submits, with privacy redaction of sensitive fields.
4. octop-browser record stop — stop capturing.
5. octop-browser record generate-steps <id> — inspect the semantic steps; record generate-skill <id> emits a draft Skill (draft.skill.md).
6. octop-browser replay run <id> — re-execute as skill-guided agentic execution (the model replays intent, not brittle coordinates/refs).

Use record list / record show <id> / record status / record doctor to manage recordings.

MCP server

octop-browser ships an MCP server, so any MCP-capable agent can drive the browser through the same tool set.

python -m octop_browser.mcp_server   # or: make mcp

It speaks MCP over stdio, which is the transport most agent clients expect.

Over MCP each action is exposed as its own tool named after it — browser_navigate, browser_click, browser_dom_tree, browser_close_session, browser_record_start, install_browser, … — rather than as a single dispatching tool. Arguments match the Python API, so browser_close_session also takes kill to terminate Chrome.

Agent skills

The skills/ directory ships ready-made Skill files for agents that support skill loading — skills/octop-browser/SKILL.md (English) and skills/octop-browser-zh/SKILL.md (Chinese). They encode the safe usage pattern: run dom-tree before every click, pass refs instead of coordinates, and reuse named profiles for login state. record generate-skill emits a draft Skill in the same format.

🚀 Quick Start

Prerequisites

• Python 3.11+ — verified on 3.11 and 3.12. Higher-level applications built on top of it (e.g. Octop) may require a newer Python; follow their own docs.
• A Chromium / Chrome binary (auto-downloaded by install-browser)

1. Install

pip install octop-browser
octop-browser install-browser    # fetch a Chromium binary once

2. Use as a library

from octop_browser import BrowserSession

async with await BrowserSession.create(profile="default") as session:
    await session.navigate("https://example.com")
    dom = await session.dom_tree()
    await session.click(ref="btn_1")

Or statelessly:

from octop_browser import browser_tool

await browser_tool(action="navigate", url="https://example.com", profile="work")

3. Use as a CLI

octop-browser --help
octop-browser --version
octop-browser navigate "https://example.com" --profile work
octop-browser dom-tree --profile work
octop-browser dom-tree --help

The top-level help lists every command and common examples. Every command also has its own help page, including nested commands such as octop-browser record start --help.

4. Record a workflow

octop-browser record daemon-start
octop-browser record start
# ... interact with the page ...
octop-browser record stop
octop-browser record generate-skill <recording_id>   # emit a draft Skill
octop-browser replay run <recording_id>              # replay it

📑 Contents

• Overview
• Highlights
• Core Technology
• Features
• Quick Start
• Reference
  • CLI reference
  • Python API
  • Configuration
  • Development
• Project Info
  • Contributing
  • Related projects
  • License

📖 CLI reference

Use octop-browser --help for the complete command list and octop-browser <command> --help for command-specific options. The --version flag prints the installed package version.