pip install omniscout

Quick Start

Start the daemon and run a command:

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

Configure default browser:

omniscout settings set browser brave

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

omniscout install --skill

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 entirely over HTTP/JSON and works with your existing Chromium browser (Chrome, Brave, Edge, Vivaldi, etc.).

Why OmniScout?

Core Commands

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"

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, delayed, or centered)
omniscout browser screenshot --full-length --out state.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 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

5. Browser Memory

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

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["DuckDuckGo / 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 = "ddg"
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.