vox-pop

<!-- mcp-name: io.github.mushfique-dgist/vox-pop -->

<div align="center">

<br>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mushfique-dgist/vox-pop/master/assets/logo-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/mushfique-dgist/vox-pop/master/assets/logo-light.svg">
  <img alt="VOX-POP" src="https://raw.githubusercontent.com/mushfique-dgist/vox-pop/master/assets/logo-dark.svg" width="420">
</picture>

### Your LLM knows what textbooks say.<br>This tells it what people *actually* think.

**9 platforms** &bull; **Semantic routing** &bull; **LLM intelligence layer** &bull; **Works without API keys**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg)](https://python.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
[![No Keys Required](https://img.shields.io/badge/API_Keys-Optional-brightgreen.svg)](#how-routing-works)

[Install](#install) &bull; [Quick Start](#quick-start) &bull; [Platforms](#platforms) &bull; [How Routing Works](#how-routing-works) &bull; [MCP Server](#mcp-server) &bull; [Claude Code Plugin](#claude-code-plugin) &bull; [Roadmap](#roadmap)

</div>

---

<br>

## Why?

<table>
<tr>
<td width="50%">

**Without vox-pop**

```
> How do I debloat my face?

Lymphatic drainage, reduce sodium,
cold compress, drink water,
sleep elevated...

(correct but soulless — same answer
 as every health blog since 2015)
```

</td>
<td width="50%">

**With vox-pop**

```
★ Searched: Reddit, 4chan /fit/, SE Fitness

Consensus (70%+ of threads):
 → Reduce sodium + 3L water/day
 → Sleep elevated on back

Controversial:
 → Gua sha: loved on Reddit,
   mocked on /fit/ as placebo

What actually worked:
 → "Cut dairy for 2 weeks — face
    visibly deflated" (847↑ r/SCA)
 → "Minox bloat is real, went away
    month 3" (/fit/, recurring)

⚠ Some suggestions are unvetted.
```

</td>
</tr>
</table>

<br>

## Install

```bash
pip install vox-pop
```

That's it. All 9 platforms work with zero API keys. Optional LLM key unlocks smarter routing (see [How Routing Works](#how-routing-works)).

<br>

## Quick Start

**CLI** — search all 9 platforms in one command:

```bash
vox-pop search "should I learn Rust or Go"
```

**Perspective mode** — see how opinions evolved over time:

```bash
vox-pop search "rust vs go" --perspective --platforms hackernews,reddit
```

```
## hackernews — Then vs Now

Historical (1+ year ago):
> "Rust vs. Go"
  — hackernews | +481 points | 580 replies | 2017-01-18

Recent (last 6 months):
> "Rust vs. Go: Memory Management"
  — hackernews | +2 points | 2025-11-15

## reddit — Then vs Now

Historical:
> "Experienced developer but total beginner in Rust..."
  — reddit | +124 points | 34 replies | 2025-03-14

Recent:
> "I rebuilt the same API in Java, Go, Kotlin, and Rust — here are the numbers"
  — reddit | +174 points | 59 replies | 2026-03-19
```

The shift tells a story: **2017 was a flame war. 2026 is domain-specific pragmatism.**

---

**Standard search** — flat results from all platforms:

```bash
vox-pop search "should I learn Rust or Go" --limit 3
```

```
### hackernews (45 found)
> "I am a full stack TypeScript dev looking to broaden my skill set..."
  — hackernews | +78 points | 42 replies | by throwaway_dev
  Source: https://news.ycombinator.com/item?id=41907717

### 4chan /g/ (12 found)
> "Rust is a mass psychosis. Go is boring but you'll actually ship..."
  — 4chan /g/ | 129 replies | by Anonymous

### reddit (8 found)
> "After 2 years with both: Rust for systems, Go for services..."
  — reddit | +234 points | 87 replies | by senior_dev_42
```

**Python** — embed in your own tools:

```python
import asyncio
from vox_pop.core import search_multiple, format_context, get_default_providers

async def main():
    results = await search_multiple(
        "best laptop for programming",
        providers=get_default_providers(),
    )
    print(format_context(results))

asyncio.run(main())
```

<br>

## Platforms

No tokens, no OAuth, no rate-limit headaches. Status is measured, not aspirational —
`vox-pop platforms --check` re-runs this against live endpoints.

> **Reddit and Lobsters are currently blocked.** Both sit behind Anubis
> proof-of-work interstitials that serve a challenge page instead of content.
> This is not a configuration issue and no header change defeats it. Reddit
> support is being moved to the official OAuth API; Lobsters now reports the
> block explicitly rather than returning an empty result.

| | Platform | Status | Source | Time Filter | Threads |
|:---:|---|:---:|---|:---:|:---:|
| ![HN](https://img.shields.io/badge/Y-FF6600?style=flat-square) | **HackerNews** | Working | [Algolia Search API](https://hn.algolia.com/api) | Yes | Yes |
| ![Reddit](https://img.shields.io/badge/r/-FF4500?style=flat-square) | **Reddit** | **Blocked** | [Pullpush](https://pullpush.io) + [Arctic Shift](https://arctic-shift.photon-reddit.com) + [Redlib](https://github.com/redlib-org/redlib) fallback | Yes | &mdash; |
| ![4chan](https://img.shields.io/badge/4-008000?style=flat-square) | **4chan** | Working | [Official JSON API](https://github.com/4chan/4chan-API) (since 2012) | &mdash; | Yes |
| ![SE](https://img.shields.io/badge/SE-F48024?style=flat-square) | **Stack Exchange** | Working | [Official API](https://api.stackexchange.com/docs) &mdash; 180+ communities | Yes | Yes |
| ![TG](https://img.shields.io/badge/TG-26A5E4?style=flat-square) | **Telegram** | Recent only | Public channel web preview (`t.me/s/`) | &mdash; | &mdash; |
| ![Lobsters](https://img.shields.io/badge/L-AC0000?style=flat-square) | **Lobsters** | **Blocked** | [lobste.rs](https://lobste.rs) JSON API + search scraping | Yes | &mdash; |
| ![Lemmy](https://img.shields.io/badge/LE-00BC8C?style=flat-square) | **Lemmy** | Working | [Public REST API](https://join-lemmy.org/api/) &mdash; federated instances | Yes | Yes |
| ![LW](https://img.shields.io/badge/LW-5F9B65?style=flat-square) | **LessWrong** | Working | [GraphQL API](https://www.lesswrong.com/graphql) | Yes | Yes |
| ![Forums](https://img.shields.io/badge/XF-E7700D?style=flat-square) | **XenForo Forums** | Flaky | HTML scraping (Head-Fi, AnandTech, etc.) | &mdash; | &mdash; |

<br>

## How Routing Works

Queries can be anything — a single word, a paragraph, an essay-length D&D rules question. vox-pop understands them all through a **four-tier routing system**:

```
User query: "i was looking into a solid laptop for linux
             something from hp, what would a savvy person pick"
                                    │
    ┌───────────────────────────────▼──────────────────────────────┐
    │  Tier 1: MCP Hints                                           │
    │  Calling LLM provides routing_hints directly                 │
    │  (skips all other tiers)                                     │
    ├──────────────────────────────────────────────────────────────┤
    │  Tier 2: LLM Query Rewrite          ← like Perplexity        │
    │  Cheap LLM call rewrites query to search-optimized form      │
    │  "hp laptop linux compatibility" + routes to communities     │
    │  Supports: Anthropic, OpenAI, Ollama (local/free)            │
    ├──────────────────────────────────────────────────────────────┤
    │  Tier 3: Semantic Embeddings         ← free, no API key      │
    │  FastEmbed (33MB model) understands meaning, not keywords    │
    │  Dynamic catalog: 77 4chan boards + 180 SE sites + static    │
    │  "contradictory spell behaviour" → SE:rpg, r/DnD, /tg/       │
    ├──────────────────────────────────────────────────────────────┤
    │  Tier 4: Broad Defaults                                      │
    │  Search popular destinations everywhere                      │
    └──────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
    Routes to: r/buildapc, r/linux, r/hardware │ /g/
               SE:hardwarerecs, SE:askubuntu │ lemmy:linux@lemmy.ml
```

**Tier 2** works like Perplexity/ChatGPT Search — the LLM rewrites your conversational query into a clean search string and picks the right communities. Set any of these env vars to enable:

```bash
ANTHROPIC_API_KEY=...   # Uses Claude Haiku (~$0.0003/query)
OPENAI_API_KEY=...      # Uses GPT-4o Mini
OLLAMA_HOST=...         # Uses local Ollama (free)
```

**Tier 3** runs entirely locally with zero API keys. A 33MB embedding model understands that "contradictory spell behaviour on a creature" means tabletop RPG rules — zero shared keywords needed. On first run, it fetches all 4chan boards and Stack Exchange sites dynamically, embeds everything, and caches to disk.

| | Cold start | Warm start | Singleton |
|---|---|---|---|
| **Tier 3 timing** | ~7s | ~1.3s | instant |

**No configuration needed.** If an LLM key is set, Tier 2 is used. Otherwise Tier 3 handles it. If fastembed isn't installed, Tier 4 (broad search) still works.

<details>
<summary><strong>Routing examples</strong></summary>

<br>

| Query | Routes to |
|---|---|
| "best hp laptop for linux" | r/buildapc, r/linux, r/hardware, /g/, SE:hardwarerecs, SE:askubuntu |
| "contradictory spell effects on a creature" | r/dndnext, r/DnD, /tg/, SE:rpg |
| "best mechanical keyboard for programming" | r/MechanicalKeyboards, /g/, SE:hardwarerecs |
| "what are the risks of yield farming" | r/CryptoCurrency, SE:tezos, telegram:ethereum |
| "how to make authentic kimchi jjigae" | r/Cooking, /ck/ |

</details>

<br>

## MCP Server

Works with **Claude Code**, **Cursor**, **Windsurf**, and any MCP-compatible client.

```json
{
  "mcpServers": {
    "vox-pop": {
      "command": "python",
      "args": ["-m", "vox_pop.server"]
    }
  }
}
```

Your LLM gets four tools:

| Tool | What it does |
|---|---|
| `search_opinions` | Sear