Metadata-Version: 2.5
Name: omniscout
Version: 0.4.17
Summary: OmniScout CLI: local-first multi-browser automation, semantic search, and research for AI agents
Project-URL: Homepage, https://omniscout.xyz
Project-URL: Repository, https://github.com/sriramramnath/omniscout
Project-URL: Documentation, https://docs.omniscout.xyz
Project-URL: Changelog, https://github.com/sriramramnath/omniscout/blob/main/cli/CHANGELOG.md
Project-URL: Issues, https://github.com/sriramramnath/omniscout/issues
Author: OmniScout
License: Modified MIT License
        
        Copyright (c) 2026 OmniScout
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        Our only modification part is that, if the Software (or any derivative works
        thereof) is used for any of your products or services, you shall prominently
        display "Powered by OmniScout" on the user interface of such product or
        service.
License-File: LICENSE
Keywords: agent,cli,patchright,research,scraping,search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: certifi>=2026.6.17
Requires-Dist: httpx-socks[asyncio]>=0.10.0
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: isodate>=0.7.2
Requires-Dist: lxml>=6.1.1
Requires-Dist: markdown-it-py>=4.2.0
Requires-Dist: markdownify>=0.13
Requires-Dist: mcp<3,>=2
Requires-Dist: mss>=10.2; sys_platform == 'win32'
Requires-Dist: nltk>=3.8
Requires-Dist: patchright>=1.61.2
Requires-Dist: platformdirs>=4.2
Requires-Dist: pyautogui>=0.9.54; sys_platform == 'win32'
Requires-Dist: pydantic>=2.7
Requires-Dist: pyperclip>=1.9; sys_platform == 'win32'
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: pywinauto>=0.6.9; sys_platform == 'win32'
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: qdrant-client>=1.9
Requires-Dist: rich>=13.7
Requires-Dist: selectolax>=0.3.21
Requires-Dist: sentence-transformers>=2.7
Requires-Dist: sniffio>=1.3.1
Requires-Dist: sumy>=0.11
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: torch>=2.2
Requires-Dist: trafilatura>=1.12
Requires-Dist: transformers>=4.40
Requires-Dist: typer>=0.12
Requires-Dist: typing-extensions>=4.16.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: train
Requires-Dist: accelerate>=0.30; extra == 'train'
Requires-Dist: datasets>=2.19; extra == 'train'
Requires-Dist: peft>=0.11; extra == 'train'
Requires-Dist: trl>=0.9; extra == 'train'
Description-Content-Type: text/markdown

<div align="center">

# OmniScout

Current release: `0.4.17`

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

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



![Python 3.11+](https://shields.io/badge/python-%3E=3.11-4584d3?style=flat-square&logo=python&logoColor=white)
[![License](https://img.shields.io/badge/license-Modified%20MIT-393939?style=flat-square)](LICENSE)
![PyPI - Version](https://img.shields.io/pypi/v/omniscout?style=flat-square&logo=pypi&logoColor=white&color=blue) ![PyPI Downloads](https://img.shields.io/pepy/dt/omniscout?style=flat-square&logo=pypi&logoColor=white&color=green)
<br>
[![macOS](https://img.shields.io/badge/macOS-8E8E93?style=flat-square&logo=apple&logoColor=white)]()
[![Linux](https://img.shields.io/badge/Linux-FFD700?style=flat-square&logo=linux&logoColor=black)]()
<br>
[![Website](https://img.shields.io/badge/Website-omniscout.xyz-2b7a78?style=flat-square)](https://omniscout.xyz) [![Docs](https://img.shields.io/badge/Docs-docs.omniscout.xyz-2b7a78?style=flat-square)](https://docs.omniscout.xyz)

![demo-terminal.png](https://pxdrop.online/raw/d9b4dbuhv1ts73baueag)


</div>

```bash
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:

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

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

```bash
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:

```bash
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:

```bash
omniscout daemon start
omniscout browser navigate https://news.ycombinator.com
omniscout browser snapshot --refs-only
omniscout browser check @e18
omniscout browser uncheck @e19
omniscout browser click '@e3'
omniscout browser close
```

Configure default browser:

```bash
omniscout settings set browser brave
```

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

```bash
omniscout settings set browser-automation headful
```

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

```bash
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`:

```bash
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:

```bash
omniscout --help
omniscout computer --help
omniscout computer ui --help
```

---

## Documentation Overview

The full documentation lives at [docs.omniscout.xyz](https://docs.omniscout.xyz) and is organized as follows:

### CLI

| Page | What it covers |
|------|----------------|
| [Overview](https://docs.omniscout.xyz/overview/) | What OmniScout is, what you get (search, browser, answers, research, graphs), installation, hello world, and configuration |
| [Agents](https://docs.omniscout.xyz/agents/) | Drop-in prompts and skill files for Claude Code, Cursor, Codex, and Kimi; multi-step agent loops; JSON output; error kinds; skill template |
| [Examples](https://docs.omniscout.xyz/examples/) | Copy-paste recipes: knowledge graphs, research, form fill, login, CAPTCHA, network capture, multi-step workflows, screenshots, PDFs, sessions, tabs, search → extract → answer, and Python/shell integration |
| [Commands](https://docs.omniscout.xyz/commands/) | Full CLI reference — every command, flag, and JSON shape: browser actions, tab/network/console management, search/extract/research/graph options, profiles, settings, workflow commands, and environment variables |
| [What is OmniScout](https://docs.omniscout.xyz/overview/) | What you get — search, browser control, answers, research — and how the pieces fit together |
| [Roadmap](https://docs.omniscout.xyz/roadmap/) | Planned features — search, extraction, page summaries, and MCP server |
| [Troubleshooting](https://docs.omniscout.xyz/troubleshooting/) | Every common failure mode and fix: login, CAPTCHA, installation, search, extraction, research, browser automation, profiles, performance, JSON output, and configuration issues |
| [Probe Zero](https://docs.omniscout.xyz/probe-zero/) | OmniScout's answer mode — what it does, how to enable it, and when to use each mode |

### SDK

| Page | What it covers |
|------|----------------|
| [SDK Overview](https://docs.omniscout.xyz/sdk/) | What the SDK is, key features, installation, quick example, and common use cases |
| [Python API Reference](https://docs.omniscout.xyz/sdk/api/) | Complete Python API docs — Search, Extraction, Research, Browser, Configuration, 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.

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?

| Feature | Status |
| :--- | :--- |
| **Local First** | No hosted browser sessions; everything stays on your machine by default |
| **Search** | Searches the web and puts the most relevant results first |
| **Always Ready** | Fast actions with persistent sessions |
| **Real Browser** | Drives your real Chrome/Brave; keeps cookies, logins, and extensions |
| **Memory** | Remember and search your browsing history |
| **Rich Extraction** | Pull structured data from any URL |
| **Agent-Ready** | Every command speaks JSON — hook it up to any AI framework |

---

## Core Commands

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

| Command | Purpose |
| --- | --- |
| `search` | Search the web, most relevant results first. |
| `answer` | Retrieve web results and synthesize an answer; preferred when you need an answer rather than a URL list. |
| `map` | List the pages on a site. |
| `warmup` | Get ready before a batch of calls. |
| `remember`, `memory` | Store and search remembered visits and notes. |
| `extract` | Return readable or structured data from a URL or query. |
| `open`, `snapshot`, `context`, `reset` | Open pages, inspect `@eN` refs, view workflow state, and reset continuity. |
| `auto` | Route a one-line request to the best command. |
| `research`, `graph` | Run full research or build entity knowledge graphs. |
| `settings`, `install` | Configure OmniScout and install agent skills or browser support. |
| `browser` | Direct Chromium automation for complex web workflows. |
| `computer` | Native desktop automation for apps, files, clipboard, and windows. |
| `daemon`, `session`, `profile` | Manage the service, persistent sessions, and browser profiles. |
| `mcp` | Serve OmniScout to MCP clients (Claude Desktop, Cursor, opencode). |
| `index`, `extract-jobs`, `crawl`, `monitor` | Manage indexes, background jobs, crawls, and URL change monitoring. |
| `record`, `macro`, `replay`, `workflow` | Record, reuse, replay, and export workflows. |
| `benchmark` | Benchmark answer modes. |

### Search

![Search](https://pxdrop.online/raw/d9bpb86hv1ts73bauf3g)

### 1. Search & Research

```bash
# 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

![Browser](https://pxdrop.online/raw/d9bpbnuhv1ts73bauf4g)

### 2. Browser Automation

```bash
# 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

![Computer](https://pxdrop.online/raw/d9bpbumhv1ts73bauf50)

### 3. Desktop Automation

```bash
# Open apps/files/URLs, type, or paste into the focused window
omniscout computer navigate /Applications/Notes.app
omniscout computer wait 300
omniscout computer type "Meeting notes"
omniscout computer paste $'First line\nSecond line'
omniscout computer paste '<b>Meeting notes</b>' --format html
omniscout computer paste '# Meeting notes' --format md
omniscout computer key cmd+s
omniscout computer key KP_0

# Clipboard, screenshots, and window management
omniscout computer clipboard set "Hello from Scout"
omniscout computer screenshot --out /tmp/desktop.png
omniscout computer screenshot --base64  # include PNG data in JSON output
omniscout computer observe --base64    # accessibility tree and screenshot together
omniscout computer screenshot --region 100,100,800,600 --out /tmp/crop.png
omniscout computer window list
omniscout computer window activate --id 0x00123456
omniscout computer window resize --id 0x00123456 --width 1200 --height 800
omniscout computer ui click @e4 --click-count 2
```

Desktop automation supports macOS, Windows, and Linux. `computer paste` inserts
plain text on all three platforms. On macOS, `--format html` or `--format md`
provides rich HTML clipboard content; the previous text clipboard is restored. Use the
ID from `computer window list` to focus, resize, or close one specific window.
Commands use the same JSON output and `--session` model as browser automation.

### Extract

![Extract](https://pxdrop.online/raw/d9bpbhehv1ts73bauf40)

### 4. Content Extraction

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```mermaid
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.

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

```toml
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:

```bash
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_DATA_DIR` | Override the default data directory |
| `OMNISCOUT_BROWSER` | Browser ID (overrides config) |
| `TWOCAPTCHA_API_KEY` | CAPTCHA solver API key |

---

## 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](LICENSE). Products built on OmniScout must prominently display **Powered by OmniScout** on the user interface.
