![\"scout](\"docs/assets/hero.png\")
\n\n \n
\n ![\"scout](\"docs/assets/demo.gif\")
\n
\n Web research plugin for Claude Code.
\n Turns vague questions into optimized multi-engine queries that reach primary sources.\n
\n Think first. Search second.\n
\n\n---\n\nClaude Code's built-in WebSearch returns 125-character snippets and relies on keyword matching alone. That's enough for simple lookups — but for real research, you need query design, source evaluation, and privacy-aware routing.\n\nscout does the thinking before the searching.\n\n## Quick Start\n\nNo API keys required. No environment changes. Install and try immediately:\n\n**1. Add the marketplace** (one-time):\n\n```bash\nclaude plugin marketplace add shidoyu/scout\n```\n\n**2. Install**:\n\n```bash\nclaude plugin install scout@shidoyu-scout\n```\n\n**3. Reload plugins** (type this inside Claude Code):\n\n```\n/mcp\n```\n\nThen ask Claude:\n\n```text\n/scout:search I want something like Git blame but for design decisions\n```\n\nscout will redesign this vague concept into the right term (ADR — Architecture Decision Records), search multiple engines with refined queries, evaluate source quality, and return an answer with a Research Trail showing exactly how it got there.\n\n## What scout does\n\n### Find concepts you can't name yet\n\n> \"I know the concept exists — something about tracking why we made each design choice — but I don't know what it's called\"\n\nscout translates fuzzy ideas into precise terminology and reaches the primary sources.\n\n### Cut through SEO noise\n\n> \"What should I actually migrate to from Terraform — not the sponsored lists, real migration stories\"\n\nPre-research acquires the right vocabulary, then targeted queries bypass content farms.\n\n### Reach official docs directly\n\n> \"How do I set up middleware in Next.js App Router?\"\n\nscout checks [Context7](https://github.com/upstash/context7) for indexed official docs first — zero web search needed if the answer is there.\n\n### Read any web page\n\n> \"Fetch and summarize https://docs.anthropic.com/en/docs/claude-code\"\n\nPrivacy-aware fetching: public pages go through cloud APIs, confidential pages stay on your machine.\n\n## Setup Levels\n\nscout works immediately after install. Each level adds capability — all optional, all reversible.\n\n### Level 1: Built-in Search (default)\n\nUses Claude Code's WebSearch. No configuration needed. This is what you get out of the box.\n\n### Level 2: Official Docs + Cleaner Fetching\n\nAdd [Context7](https://github.com/upstash/context7) for direct library/framework doc access. Jina Reader strips page noise so less text fills your context, saving tokens. Works without a key (20 req/min); a free API key unlocks 500 req/min.\n\n### Level 3: Semantic Search\n\nAdd [Exa](https://exa.ai) for meaning-based search — finds relevant pages even when you don't know the right keywords. Basic semantic search works with a free tier; API key unlocks advanced features.\n\n### Level 4: Local Browser\n\nAdd [Playwright](https://playwright.dev) for JavaScript-rendered pages and confidential URLs that should never leave your machine. Downloads Chromium (~200MB).\n\n**Run `/scout:setup` to walk through each level interactively.** Every step shows exactly what will be added to your configuration before any changes are made. Re-run anytime to add or update tools.\n\n## Skills\n\n| Skill | Purpose |\n|---|---|\n| `/scout:search` | Multi-engine web search with query design, source evaluation, and automatic re-search |\n| `/scout:fetch` | URL content fetching with automatic privacy classification |\n| `/scout:setup` | Interactive guided setup for search engines and fetching tools |\n\n### Research Trail\n\nEvery search ends with a structured trail showing how scout reached its answer:\n\n```\n🔍 Research Trail\n───────────────────────────────\nQuery: your original question\nDesigned queries: the optimized queries scout actually ran\nSources: URLs with reliability tier (🟢 primary / 🟡 secondary / ⚪ tertiary)\nRe-searches: any additional searches and why\nConfidence: High / Medium / Low with rationale\n```\n\n## Privacy\n\nscout classifies URLs into three tiers before fetching:\n\n| Classification | Routing | Examples |\n|---|---|---|\n| **Public** | Cloud APIs (r.jina.ai / WebFetch) | Blogs, docs, GitHub public repos |\n| **Confidential** | Local Playwright only | localhost, internal wikis, admin panels |\n| **Authenticated** | Playwright CDP (your browser session) | Notion, Slack, post-OAuth pages |\n\nThis classification is based on LLM judgment, not system enforcement. Treat it as best-effort routing. For highly sensitive data, verify the classification before proceeding.\n\n**Confidential URLs are never sent to external APIs, even on failure** — the system does not fall back to cloud tools for confidential pages.\n\n