pip install omniscout

Requirements: Python 3.11 or newer and a Chromium-based browser such as Chrome, Brave, Edge, Vivaldi, Opera, Arc, or Chromium. OmniScout stores browser profiles, indexes, caches, and downloaded models locally. The first search or answer may download and warm an embedding model.

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 Daemon: connected.

Quick Start

Warm the local models, search, open a result in the managed browser, and inspect the page for accessibility references:

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

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.

A long-lived daemon at 127.0.0.1:7720 provides sub-second browser actions, a warm embedding model, and a local vector store. It communicates over HTTP/JSON and works with your existing Chromium browser (Chrome, Brave, Edge, Vivaldi, etc.). Local state and processing stay on your machine, while search, crawling, extraction, and browser automation still access the external websites or providers 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

# Semantic web search
omniscout search "state of local AI agents 2026"

# Summarized one-sentence answer (no LLM)
omniscout answer "Who is the president?" --depth balanced

# Full research pipeline (search → crawl → extract → rerank → summarize)
omniscout research "emerging quantum computing startups 2026"

# Open the local OmniScout Search UI (bundled SearXNG at 127.0.0.1:8888)
omniscout search ui

Browser

2. Browser Automation

# Navigate and identify elements with accessibility tree refs
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

# macOS MVP: 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 via native open, AppleScript, screencapture, and clipboard tools. Commands use the same daemon JSON envelope 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

# Exa-style schema-driven extraction (no LLM)
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 Unicode tree
omniscout graph "Cursor"              # search web and extract
omniscout graph "Cursor" -w cursor.com --data  # crawl site directly
omniscout graph "Cursor" --llm        # optional LLM overlay on evidence

6. Browser Memory

# Remember and semantically 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 through native OS tools.

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.

Architecture

flowchart LR
    A["AI agent (Claude / Cursor / Codex / Kimi)"] --> B["OmniScout CLI<br/>(typer + rich)"]
    B -->|"HTTP POST"| C["Daemon<br/>(127.0.0.1:7720)"]
    C --> D["Patchright Backend"]
    C --> E["Extension Backend<br/>(opt-in)"]
    C --> F["Embed Service<br/>(warm model)"]
    B --> G["Search / Extract / Research / Graph"]
    G --> H["Local Qdrant"]
    G --> I["SearXNG / Crawler"]
    D --> J["Chrome / Brave / Edge / Vivaldi"]

For contributors:

cli/omniscout/
  app.py              # Typer root
  commands/           # CLI subcommands
  daemon/             # HTTP server, backends, replay
  engines/            # browser, search, research, extractor, crawler
  store/              # SQLite cache, sessions, workflow, memory
  models.py           # Pydantic JSON contracts

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"

Or talk to the daemon directly:

curl -X POST http://127.0.0.1:7720/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"navigate","args":{"url":"https://example.com"},"session":"demo"}'

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):

default_source = "searxng"   # searxng | ddg | wikipedia | web
search_limit = 10
research_results = 8
request_throttle_seconds = 1.0
embedding_model = "sentence-transformers/all-MiniLM-L6-v2"
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

Legacy HARNESS_* equivalents accepted.

On-disk State

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.