omniscout 0.4.1

OmniScout CLI: local-first multi-browser automation, semantic search, and research for AI agents

OmniScout

Local-first browser automation, semantic search & research for AI agents.

No cloud APIs. No hosted sessions. No lock-in. Just a fast, local HTTP daemon in your terminal.

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

Page	What it covers
Overview	What OmniScout is, what you get (daemon, backends, @eN refs, search/extract/research/graph engines, Probe Zero), design principles, installation, hello world, data layout, and configuration
Agents	Drop-in prompts and skill files for Claude Code, Cursor, Codex, and Kimi; multi-step agent loops; JSON contract; trace / replay / watch; error kinds; skill template
Examples	Copy-paste recipes: knowledge graphs, research, form fill, login + profile reuse, CAPTCHA, network capture, multi-step workflows, screenshots, PDFs, sessions, tabs, search → extract → answer, and Python/shell integration
Commands	Full CLI reference — every command, flag, and JSON shape: daemon lifecycle, browser action vocabulary, tab/network/console management, search/extract/research/graph options, profiles, settings, workflow commands, response envelope, and environment variables
Architecture	Daemon, backends (Playwright vs Extension), @eN snapshot refs, action queue, snapshot generations, action history & replay, session restore, event stream, and all core layers (commands, engines, daemon, storage, config, models) with data-flow diagrams
Roadmap	Planned features — multi-provider search, smart extraction, page summaries, and MCP server
Troubleshooting	Every common failure mode and fix: @eN refs, login, CAPTCHA, extension backend, installation, runtime, search, extraction, research, browser automation, profiles, daemon, performance, cache, JSON output, and configuration issues
Probe Zero	OmniScout's local answer engine — what it does, how to enable it, Classic vs Probe Zero, and gold-benchmark metrics

SDK

Page	What it covers
SDK Overview	What the SDK is, key features, installation, quick example, and common use cases
Python API Reference	Complete Python API docs — Search, Extraction, Crawler, Research, Browser, Daemon Client, Configuration, Models, Logging, async support, testing, performance tips, and troubleshooting

---

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?

Feature	Status
Local First	No API keys, no remote browsers, no data leaving your laptop
Semantic Search	Searches the web and re-ranks results using local sentence-transformers embeddings
Long-lived Daemon	Sub-second per-action latency with persistent sessions
Real Browser	Drives your real Chrome/Brave; keeps cookies, logins, and extensions
Semantic Memory	Remember and search your browsing history with vector embeddings
Rich Extraction	Pull structured data from any URL with zero LLM calls
Agent-Ready	Every command speaks JSON — hook it up to any AI framework

---

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["Playwright 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

Variable	Purpose
OMNISCOUT_JSON=1	Force JSON output on every command
OMNISCOUT_DAEMON_AUTO_START=0	Don't auto-start the daemon
OMNISCOUT_DAEMON_PORT	Daemon port (default: 7720)
OMNISCOUT_DATA_DIR	Override the default data directory
OMNISCOUT_BROWSER	Browser ID (overrides config)
OMNISCOUT_EMBED_LOCAL_ONLY=0	Allow runtime Hugging Face fetches
TWOCAPTCHA_API_KEY	CAPTCHA solver API key

Legacy HARNESS_* equivalents accepted.

---

On-disk State

Path	Purpose
profiles/	Persistent Chrome user-data-dirs
qdrant/	Embedded vector index
models/sentence-transformers/	Prefetched embedding model
memory.sqlite	Browser memory (visits + notes)
sessions.sqlite	Long-lived browser session registry
cache/pages/	Content-hashed HTML cache
daemon/	PID, port, logs, action history, session restore

---

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.