omnireach

English · 中文

Your agent reads Twitter. It still can't read WeChat. omnireach fixes that.

omnireach searches Google and the login-walled Chinese internet — 微信公众号 · 小红书 · 抖音 · B站 · TikTok — plus Twitter, Reddit, HN, YouTube and more, through one uniform interface: omnireach search returns one normalized JSON schema across every source, omnireach fetch returns clean markdown for any URL. WeChat search works with zero config — no key, no login:

omnireach search --on wechat "Claude Code 技巧"   # works 60 seconds after install

Installed as a Claude Code skill, so your agent just knows how to use it next session. No LLM inside, no per-call scraping fees — the heavy sources reuse your own browser session.

MCP before Playwright

For search and reading, start with two read-only MCP tools instead of browser automation. Ordinary page fetches never start Chrome. Google, Reddit, Twitter, Xiaohongshu, TikTok, and Douyin search now use Omnireach's own small, read-only Chrome bridge first, with OpenCLI retained as a compatibility fallback. Browser-backed calls use temporary background tabs that close after the call, and quick mode remains browser-free. Keep Playwright for clicks, forms, file transfer, screenshots, and visual assertions.

On the recorded machine, Playwright took 2.7x as long on the cold path and 1.3x as long with both runtimes warm. See the method and limitations or inspect every raw sample.

Install — just tell your agent

"Install omnireach"

Your agent runs one command. You copy nothing.

Manual fallback — paste into your terminal if you prefer:

curl -fsSL https://raw.githubusercontent.com/Daily-AC/omnireach/main/install.sh | sh

Also on PyPI: uv tool install omnireach or pip install omnireach (CLI only — the one-liner above additionally registers the Claude Code skill). Try without installing: uvx omnireach search "vibe coding".

This installs the CLI and registers the Claude Code skill (auto-discovered next session). Zero-config sources — HackerNews, RSS, 微信 (Sogou path), B站 — work immediately. Other sources open up after a one-time setup step each.

Installing the repository as a Claude Code plugin also registers the bundled MCP server. The standalone installer keeps the CLI fallback available even when the client has not loaded plugin MCP configuration.

What you get

1. Reach the unreachable. Twitter, Reddit, 小红书, 微信公众号, 抖音, B站, TikTok — login-walled vertical platforms that no agent web search reaches. omnireach reads them through your own logged-in browser session. Its native Chrome bridge handles all six browser-backed search sources, with OpenCLI retained as a compatibility fallback.

2. One uniform contract. omnireach search → normalized metadata + URL, same shape across every source. omnireach fetch → clean markdown for any URL, with host-aware routing: ordinary pages use a built-in HTTP extractor with Jina fallback, while mp.weixin.qq.com uses your logged-in Chrome session. No Playwright or Crawl4AI is required for the default path.

3. Works even when WebSearch doesn't. On proxy / relay-station / Bedrock / Vertex-Claude-3.x setups where the built-in WebSearch server tool isn't available, omnireach gives search back — it runs entirely on the client side, bypassing both gate layers.

Agent fast path — MCP before Playwright

The plugin exposes two model-controlled tools:

• omnireach_search for web research and platform search
• omnireach_fetch for reading an HTTP or HTTPS URL as Markdown

Both tools are served by the dependency-free stdio command:

omnireach mcp

For MCP clients that do not load the plugin, register it with:

{
  "mcpServers": {
    "omnireach": {
      "command": "omnireach",
      "args": ["mcp"]
    }
  }
}

Use these tools before Playwright for read-only work. Ordinary page fetches do not start Chrome. Login-backed adapters may use the user's existing Chrome session through a hidden, ephemeral tab that is released after the call. Keep Playwright for clicks, forms, uploads, downloads, screenshots, visual assertions, and unsupported interactive workflows.

How is this different from Agent-Reach?

Agent-Reach (51k★) created this category and is excellent at what it does. omnireach makes different trade-offs — these are date-stamped facts, not marketing:

Pick Agent-Reach if you need Facebook/LinkedIn/transcription. Pick omnireach if you need the Chinese internet — WeChat above all — a machine-stable JSON contract, or a single fetch entrypoint. Both MIT; they compose fine in one agent.

Example

# Search a login-walled vertical platform
omnireach search --on xiaohongshu --json "Claude Code 使用技巧"

# Fetch a WeChat article — login-walled, via your session
omnireach fetch --json "https://mp.weixin.qq.com/s/<token>"

# Full pipeline: search → fetch all results
omnireach search --on wechat --json "claude 4.7" \
  | jq -r '.results[].url' \
  | xargs -I{} omnireach fetch --json {}

Commands

Sources

Native browser sources: Run omnireach bridge install, load the printed directory once from chrome://extensions as an unpacked extension, and sign in to the sites you need in that Chrome profile. auto prefers this dependency-free native path for Google, Reddit, Twitter, Xiaohongshu, TikTok, and Douyin, then falls back to OpenCLI. Set OMNIREACH_BROWSER_TRANSPORT=native to verify that OpenCLI is not invoked.

agy grounded search: Keep an authenticated agy CLI process running, create a dedicated conversation, then run omnireach agy configure <conversation-id>. Verify it with omnireach agy status --json and search explicitly with omnireach search --on agy --json "query".

WeChat fetch: zero-config Sogou search now resolves signed result links to direct mp.weixin.qq.com URLs in the same HTTP session. Fetch then uses the Daily-AC/OpenCLI fork (weixin download --stdout, upstream PR jackwener/OpenCLI#1770) in an explicit background, ephemeral tab and releases it after the command.

Agent calling convention

Prefer the MCP tools: call omnireach_search for research, then omnireach_fetch for selected URLs. Fall back to the CLI only when MCP is unavailable. When using that fallback, always request JSON explicitly:

# Option 1: explicit flag per command
omnireach search --json "..."
omnireach fetch  --json "<url>"

# Option 2: env var (recommended for agent harnesses)
export OMNIREACH_FORCE_JSON=1

The not isatty() auto-JSON added in v0.9.2 covers most cases, but some agent terminals (e.g. Antigravity) allocate a real PTY to subprocesses making isatty()=True. Explicit --json or the env var always works. When --json is present, CLI usage errors are also emitted as a JSON error envelope on stdout. Fetch rejects short verification and login-wall placeholders instead of treating any non-empty body as success; Reddit failures include a logged-in OpenCLI fallback hint.

Full skill contract: skills/omnireach/SKILL.md

Claude Code's WebSearch is a server-side server tool (web_search_20250305). Whether it actually works depends on two independent gates:

Gate 1 — client-side (WebSearchTool.isEnabled() checks getAPIProvider()):

• Default firstParty (no CLAUDE_CODE_USE_* env var set, including the case where only ANTHROPIC_BASE_URL is changed) → tool registered
• Explicit CLAUDE_CODE_USE_BEDROCK=1 → tool off
• Explicit CLAUDE_CODE_USE_VERTEX=1 + Claude 4+ → registered; older Claude → off
• Explicit CLAUDE_CODE_USE_FOUNDRY=1 → registered

Gate 2 — upstream server tool implementation: After the client sends the tool schema, the upstream API must have specifically implemented the web_search_20250305 server tool (receive tool call → run search → return results to client):

• Real Anthropic API (api.anthropic.com): ✓ native
• Vertex / Foundry: ✓ (each backend implements it)
• Third-party providers that specifically support Claude Code (e.g. DeepSeek's Anthropic-compat endpoint): ✓ they implemented the server tool handling, routing to their own search backend
• OpenAI-compatible relay stations (cliproxy / anyrouter etc. that simply translate Claude API → OpenAI Chat Completions): ✗ don't recognize server tool semantics
• Self-hosted gateways / most proxies: ✗ generally not implemented

Gate 2 looks at "did the upstream specifically implement Claude Code server tool support" — not at "is this real Anthropic." Providers who specifically support Claude Code implement it; pure API translators don't. (Data point: DeepSeek is not real Anthropic but WebSearch works because they explicitly implemented it.)

Root causes differ by scenario:

• DeepSeek and other Claude-Code-specific third parties: both gates pass, WebSearch ✓ — omnireach value here is supplementing vertical sources (Twitter/小红书/微信), not patching search
• OpenAI-compatible relay station users: client registers the tool, upstream doesn't handle the server tool call → failure
• Explicit Bedrock users / Vertex Claude 3.x users: client-side isEnabled is off before the request even leaves

Even with WebSearch working, it can't reach Twitter threads, Reddit comment sections, 小红书 posts, WeChat articles, 抖音, B站 technical videos — these login-walled vertical platforms are blind spots for every hosted web search. omnireach's three value layers:

1. Patch for users whose client-side gate is off
2. Patch for users whose upstream doesn't implement the server tool
3. Supplement for users whose WebSearch works fine but can't reach vertical platforms

omnireach = omni (all) + reach (reach). Full "reach the whole web" semantics require three capability layers, all living as sibling binaries in this repo (analogous to cargo / rustc / rustfmt in the Rust monorepo — no sister repo):

v0.10+ has omnireach covering search + fetch (subcommand form). Video parsing still uses external tools (yt-dlp / whisper); parse binary will be added to this repo when there are real user requests (YAGNI — no sister repo).

This split mirrors Anthropic's own WebSearch + WebFetch split: each layer does one thing well, search isn't slowed by parsing tasks, and agent callers can compose freely.

Note: renaming omnireach to omnisearch was considered, but v0.10 landing omnireach fetch resolved the question — omnireach search (reach = find) + omnireach fetch (reach = retrieve) are both natural sub-actions of "reach," so the umbrella name fits. No rename (decided 2026-05-27).

omnireach is in alpha with frequent releases. Check and upgrade:

omnireach check-update                                                            # compare against GitHub Releases
uv tool install --force git+https://github.com/Daily-AC/omnireach.git             # pull latest

⚠️ uv tool upgrade omnireach will not pull new commits (uv locks git-URL-installed tools to the commit at install time). --force reinstall fetches the latest.

Run omnireach doctor to print a platform / Python version line at the top — useful to include when filing issues.

omnireach is free by default. Configuring a paid API key improves result quality:

omnireach setup tavily       # guided key entry + writes to ~/.omnireach/secrets.env
omnireach setup brave
omnireach setup perplexity
omnireach setup exa          # added v0.5 (replaces old `web` source)

Keys are detected automatically when set. Results carry cost="paid" metadata; TTY output shows a 💎 prefix for auditability.

To disable: edit ~/.omnireach/preferences.toml and set [boosters] auto_enable = false.

~/.omnireach/preferences.toml can configure default sources, language, output format, and source_trust overrides.

omnireach preferences show     # view current config
omnireach preferences edit     # open in $EDITOR
omnireach preferences reset    # reset (backs up original to .bak)
omnireach preferences path     # print file location

omnireach is the search layer — the content field is uniformly capped at ≤ 500 characters + …. This validator runs in the contract layer (SearchResult.content pydantic field_validator) for all sources. This is intentional — full text belongs to the omnireach fetch layer (see Naming & architecture above).

For sources whose upstream returns full text (wechat / exa / tavily) or long threads (twitter), the complete raw payload is preserved in result.raw, so agents that need full text can retrieve it:

# Python (call CLI + parse JSON envelope)
import json
import subprocess

out = subprocess.run(
    ["omnireach", "search", "--json", "--on", "wechat", "claude 4.7"],
    check=True, capture_output=True, text=True,
)
env = json.loads(out.stdout)
snippet = env["results"][0]["content"]        # 500 chars + "…"
full    = env["results"][0]["raw"]["text"]    # Exa / wechat / twitter full text
# tavily uses raw["content"]

# CLI + jq
omnireach search --json --on tavily "claude 4.7" | \
  jq '.results[] | {title, snippet: .content, full: .raw.content}'

Field mapping (verified by real E2E in v0.8.1 + v0.9):

The specific key names in raw[...] match upstream API schema directly — if upstream changes schema, this table needs updating. When uncertain, inspect result.raw.keys() first.

Other sources (HN / GitHub / RSS / YouTube / etc.) generally have content under 500 chars, so the validator is usually a no-op — but it's not guaranteed. For full-text fallback, check result.raw for a matching key.

For actual full text → omnireach fetch <url> (v0.10+)

omnireach fetch <url> is the official search → full-text pipeline, with host-aware backend routing:

# Any webpage → built-in HTTP extractor, then Jina fallback if blocked
omnireach fetch https://example.com/article --json

# WeChat Official Account article → automatically uses OpenCLI logged-in Chrome (v0.10.1+), bypasses CAPTCHA
omnireach fetch https://mp.weixin.qq.com/s/<token> --json

# search → fetch pipeline
omnireach search --on wechat "claude 4.7" --json \
  | jq -r '.results[].url' \
  | xargs -I{} omnireach fetch --json {}

Backend matrix:

Explicit --backend overrides auto:

CAPTCHA-shaped responses are rejected rather than returned as successful article content. Auto mode records captcha_suspected in errors[] and tries the next backend; if all backends fail, JSON is still emitted but the process exits non-zero. omnireach doctor reports both the built-in HTTP backend and whether OpenCLI supports the background-tab contract.

See docs/superpowers/specs/2026-05-25-omnireach-design.md.

MIT — see LICENSE.