---
name: trufflejar
description: Mine Reddit through Trufflejar — a subreddit's posts, full threads, and clustered unanswered questions as JSON, via the hosted API (key in ~/.config/trufflejar/.env) or locally with your own residential proxy. Use when the user asks to mine Reddit, find unanswered questions or content gaps in a subreddit, pull posts or a comment thread, or research what a community is asking. Triggers on "mine reddit", "trufflejar", "subreddit questions", "content gaps", "what is r/X asking", "unanswered questions on reddit".
---

# Trufflejar

Reddit mining as three verbs: `posts` (a subreddit's posts), `thread` (one
thread, full comment tree), `mine` (scan N threads → detect questions → flag
unanswered → cluster by topic). Reddit blocks datacenter IPs and automated
clients; Trufflejar clears the JS challenge with real headless browsers behind
residential proxies, so you don't have to.

## Hosted lane (default)

Key: `TRUFFLEJAR_API_KEY` from the environment or `~/.config/trufflejar/.env`.
No key? Send the user to https://www.trufflejar.com/connect — the paste block
there pairs this skill. Base URL is ALWAYS `https://www.trufflejar.com` (the
apex redirect drops Authorization headers).

```bash
KEY=$(grep '^TRUFFLEJAR_API_KEY=' ~/.config/trufflejar/.env | cut -d= -f2)

# Posts: sort top|hot|new|rising · time hour|day|week|month|year|all · limit ≤100 (~30s)
curl -s "https://www.trufflejar.com/api/v1/posts?subreddit=ClaudeAI&sort=top&time=week&limit=30" \
  -H "Authorization: Bearer $KEY"

# Thread: full comment tree, limit ≤1000 (~30s)
curl -s "https://www.trufflejar.com/api/v1/thread" \
  -H "Authorization: Bearer $KEY" \
  -G --data-urlencode "url=https://www.reddit.com/r/<sub>/comments/…"

# Mine: threads ≤100, optional topic_keywords regex → 202 {job_id}
curl -s -X POST https://www.trufflejar.com/api/v1/mine \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"subreddit": "<sub>", "threads": 30, "time": "month"}'
```

A mine runs ~40–90s: poll `GET /api/v1/jobs/{job_id}` (same auth) every ~10s
until `status` is `done` or `error`. Small mines (≤10 threads) can instead use
`POST /api/v1/mine?wait=1` to hold the request and get the result directly.

Reading a mine result: `result.top_questions` = highest-scored unanswered
questions (`q`, `score`, `n_replies`, `permalink`, `thread_title`);
`result.clusters_unanswered` = topic clusters; `n_questions`/`n_unanswered`
for the headline numbers. Every response carries `bandwidth` (real wire MB +
estimated cost).

Errors: 401 → key missing/revoked (re-pair via /connect); 400 → bad params
(message says what to fix); 502 → the miner run failed, retry once (flagged
proxy exits rotate on the next run).

## Local lane (free, bring your own residential proxy)

The same single-file engine, run on this machine — for users who'd rather not
use the hosted API. Full setup and commands:
https://www.trufflejar.com/connect.md is the hosted pairing; for local, see
the repo README at https://github.com/johnkueh/trufflejar-miner. Short
version:

```bash
npm i -g agent-browser && agent-browser install   # headless Chrome
curl -fsSL https://www.trufflejar.com/cli.ts -o ~/.trufflejar/cli.ts
bun ~/.trufflejar/cli.ts setup --proxy "http://user:pass@host:port"  # residential
bun ~/.trufflejar/cli.ts doctor                    # every line should PASS
bun ~/.trufflejar/cli.ts mine --subreddit <sub> --time month --threads 30
```

Same JSON shapes as the API, on stdout. Never run it through a datacenter IP
without a residential proxy — Reddit flags it and direct connections from the
user's own IP can get their home IP blocked at mine scale.