pip install omniscout

Requirements: Python 3.11 or newer and a Chromium-based browser such as Chrome, Brave, Edge, Vivaldi, Opera, Arc, or Chromium. Everything stays on your machine.

Verify the installation and inspect available commands:

omniscout --version
omniscout --help
omniscout computer doctor       # diagnose desktop automation (macOS)

Set up the default browser and download the existing-browser extension:

omniscout setup --browser dia

The command downloads the extension and opens the selected browser's extensions page. Choose Load unpacked, select the printed folder once, and confirm that its popup says connected.

Quick Start

Get ready, search, open a result in the browser, and inspect the page:

omniscout warmup
omniscout answer "latest AI news"
omniscout open
omniscout snapshot --refs-only
omniscout browser click '@e3'

For a direct URL, use the browser command group:

omniscout daemon start
omniscout browser navigate https://news.ycombinator.com
omniscout browser snapshot --refs-only
omniscout browser click '@e3'
omniscout browser close

Configure default browser:

omniscout settings set browser brave

Automation runs in a managed background window by default. To use your own browser instead:

omniscout settings set browser-automation headful

Install agent skill files so Claude Code, Cursor, and Codex auto-discover OmniScout:

omniscout install --skill

The installer currently writes skill files for Claude Code, Cursor, Codex CLI, and Gemini CLI. Other agents can use the bundled SKILL.md manually.

For deterministic agent integration, use --json or set OMNISCOUT_JSON=1:

omniscout --json answer "What is local-first software?"
export OMNISCOUT_JSON=1

When you need to discover a command or option, use the built-in help:

omniscout --help
omniscout computer --help
omniscout computer ui --help

Documentation Overview

The full documentation lives at docs.omniscout.xyz and is organized as follows:

CLI

SDK

What It Is

OmniScout is a self-contained terminal-native interface for the web. Think of it as a local browser brain for AI agents — enabling them to search, browse, extract structured data, and remember everything without ever leaving your laptop.

It works with your existing Chromium browser (Chrome, Brave, Edge, Vivaldi, etc.). Everything stays on your machine, while search, extraction, and browser automation access the websites you request.

Why OmniScout?

Core Commands

The following is the complete beginner-oriented command map. Run any command with --help for its flags and subcommands.

Search

1. Search & Research

# Web search
omniscout search "state of local AI agents 2026"

# Summarized one-sentence answer
omniscout answer "Who is the president?" --depth balanced

# Full research from many sources
omniscout research "emerging quantum computing startups 2026"

# Open the local OmniScout Search UI
omniscout search ui

Browser

2. Browser Automation

# Navigate and identify elements
omniscout browser navigate https://news.ycombinator.com
omniscout browser snapshot --refs-only
omniscout browser click '@e3'

# Screenshots: full page, scroll-stitched, element, or pixel region
omniscout browser screenshot --full-length --out state.png
omniscout browser screenshot --stitched --out state-stitched.png
omniscout browser screenshot --ref '#hero' --out hero.png
omniscout browser screenshot --region 0,200,1280,800 --out mid.png
omniscout browser screenshot --delay 2 --out after-load.png

# Capture network and console logs
omniscout browser network list
omniscout browser console tail

Computer

3. Desktop Automation

# Open apps/files/URLs and type into the focused window
omniscout computer navigate /Applications/Notes.app
omniscout computer wait 300
omniscout computer type "Meeting notes"
omniscout computer key cmd+s

# Clipboard, screenshots, and window management
omniscout computer clipboard set "Hello from Scout"
omniscout computer screenshot --out /tmp/desktop.png
omniscout computer screenshot --region 100,100,800,600 --out /tmp/crop.png
omniscout computer window list

Desktop automation currently supports macOS. Commands use the same JSON output and --session model as browser automation.

Extract

4. Content Extraction

# Clean Markdown or structured JSON from any page
omniscout extract https://example.com
omniscout extract -q "SpaceX founder" --format structured --fields founder

# Schema-driven extraction
omniscout extract https://stripe.com/pricing \
  --schema-inline '{"type":"object","properties":{"pricing":{"type":"string"}}}'

5. Knowledge Graphs

# Map a company or person into a structured tree
omniscout graph "Cursor"              # search web and extract
omniscout graph "Cursor" -w cursor.com --data  # use a specific site
omniscout graph "Cursor" --llm        # optional AI overlay on results

6. Browser Memory

# Remember and search your browsing history
omniscout remember https://example.com/blog/post
omniscout memory "neural networks in production"

Desktop automation reference

computer supports navigate, type, key, screenshot, wait, doctor, clipboard, window, ui, and backend. The computer ui group supports snapshot, click, drag, and is; use its @eN references for element-level actions. Desktop automation currently supports macOS.

Reusable workflow example

omniscout record start --name my_macro
omniscout browser navigate https://example.com
omniscout browser snapshot --refs-only
omniscout record stop my_macro
omniscout macro run my_macro

Development

cd cli
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .

Tests live in cli/tests/. Integration tests are marked with integration and may start subprocesses or bind local ports. Keep browser profiles and generated model/cache data outside the repository.

How it fits together

flowchart LR
    A["AI agent (Claude / Cursor / Codex / Kimi)"] --> B["OmniScout CLI"]
    B --> C["Browser"]
    B --> G["Search / Extract / Research / Graph"]
    C --> J["Chrome / Brave / Edge / Vivaldi"]

JSON & Agent Integration

Every command speaks JSON. Set OMNISCOUT_JSON=1 and stdout becomes a structured payload.

export OMNISCOUT_JSON=1
omniscout search "robotics simulators"

Configuration

Create a config.toml in your config directory (e.g. ~/.config/omniscout/config.toml on Linux, ~/Library/Application Support/omniscout/config.toml on macOS):

search_limit = 10
research_results = 8
request_throttle_seconds = 1.0
browser = "chrome"                    # chrome | edge | brave | vivaldi | opera | arc | chromium | custom
# browser_executable = "/path/to/browser"  # only needed for 'custom'

Or configure via CLI:

omniscout settings browsers
omniscout settings set browser brave
omniscout settings show

Environment Variables

Supported By

OmniScout works with any AI agent that can run shell commands. Skill files are auto-installed with omniscout install --skill wherever a well-known directory exists.

Agents with verified skill directories:

• Claude Code — ~/.claude/skills/
• OpenAI Codex CLI — ~/.codex/skills/
• Cursor — ~/.cursor/skills-cursor/
• Gemini CLI / Antigravity — ~/.gemini/config/skills/
• Pi — paste SKILL.md into the system prompt
• OpenCode — paste SKILL.md into the system prompt
• Windsurf — paste SKILL.md into the system prompt
• Cline — paste SKILL.md into the system prompt
• Roo Code — paste SKILL.md into the system prompt
• Amp — paste SKILL.md into the system prompt
• Replit Agent — paste SKILL.md into the system prompt
• AiderDesk — paste SKILL.md into the system prompt
• AstrBot — paste SKILL.md into the system prompt
• Droid (Factory) — paste SKILL.md into the system prompt
• Goose — paste SKILL.md into the system prompt
• Factory — paste SKILL.md into the system prompt

Also works with: GitHub Copilot (Agent Mode), any custom agent with shell access, or any coding assistant that can invoke the omniscout / scout CLI binary.

The CLI is the interface. If your agent runs bash, it runs OmniScout.

License

Modified MIT — see LICENSE. Products built on OmniScout must prominently display Powered by OmniScout on the user interface.