Reddit Research

General-purpose Reddit research agent. Search, read, monitor — all from the terminal. No API key needed.

Why?

Reddit is the largest collection of authentic human opinions on the internet. Unlike SEO-optimized blog posts or sponsored content, Reddit threads contain real experiences, tested solutions, and unfiltered takes.

Zero auth. Zero cost. Zero dependencies.

Data Providers

Provider	Flag	Best For	Limitation
Reddit (default)	--provider reddit	Real-time data, feeds, threads	~60 req/min
PullPush	--provider pullpush	Historical/deleted posts, global comment search	Sometimes down
Arctic Shift	--provider arctic-shift	Archived data, deep history	Requires --sub or --author

Default is Reddit (real-time). Switch to PullPush or Arctic Shift when you need historical data or deleted content.

Setup

Node.js 18+ required (for native fetch). No npm install needed.

cd <skill-dir>/scripts

CLI Tool

Search

npx tsx reddit.ts search "<query>" [options]

Options: - --sub <subreddit> — restrict to a subreddit - --sort relevance|top|new|hot|comments — sort order (default: relevance) - --time hour|day|week|month|year|all — time filter (default: week) - --limit N — max results (default: 15) - --provider reddit|pullpush|arctic-shift — data source - --author <username> — filter by author (Arctic Shift only) - --compact — one-line format - --save — save results to file - --json — raw JSON output - --markdown — markdown formatted output

Examples:

npx tsx reddit.ts search "pumpfun scam" --sort top --time month
npx tsx reddit.ts search "best VPN" --sub privacy --sort top --time year
npx tsx reddit.ts search "openclaw" --provider pullpush --limit 20
npx tsx reddit.ts search "agent" --provider arctic-shift --sub openclaw

Comment Search

Search through comments using PullPush or Arctic Shift:

npx tsx reddit.ts comments "<query>" [--sub <subreddit>] [--provider pullpush|arctic-shift] [--limit N]

npx tsx reddit.ts comments "solana scam" --provider pullpush --limit 10
npx tsx reddit.ts comments "openclaw" --provider arctic-shift --sub openclaw

Subreddit Feeds

npx tsx reddit.ts hot <subreddit> [--limit N] [--time day|week]
npx tsx reddit.ts new <subreddit> [--limit N]
npx tsx reddit.ts rising <subreddit> [--limit N]
npx tsx reddit.ts top <subreddit> [--time day|week|month|year|all] [--limit N]
npx tsx reddit.ts controversial <subreddit> [--time day|week] [--limit N]

Multi-Subreddit Feed

npx tsx reddit.ts multi <sub1+sub2+sub3> [--sort hot|new|top] [--time day|week] [--limit N]

Read Thread

npx tsx reddit.ts thread <url> [--sort top|best|new|controversial] [--limit N] [--depth N]

User Profile

npx tsx reddit.ts user <username> [--posts|--comments] [--sort new|top|hot] [--limit N]

Subreddit Info

npx tsx reddit.ts subreddit <name>

Find Subreddits

npx tsx reddit.ts find-subs "<query>" [--limit N]

Popular Subreddits

npx tsx reddit.ts popular [--limit N]

Cross-Posts / Duplicates

npx tsx reddit.ts duplicates <post_id>

Wiki

npx tsx reddit.ts wiki <subreddit> [page]

Watchlist

npx tsx reddit.ts watchlist                       # Show all
npx tsx reddit.ts watchlist add <sub> [note]      # Add subreddit
npx tsx reddit.ts watchlist remove <sub>          # Remove
npx tsx reddit.ts watchlist check                 # Check hot posts from all

Cache

npx tsx reddit.ts cache stats     # Cache statistics
npx tsx reddit.ts cache clear     # Clear all cached data

Research Loop (Agentic)

When doing deep research, follow this loop:

1. Decompose the Question

Turn the research question into 3-5 search queries: - Direct query: Core keywords - Subreddit-specific: Search within the most relevant sub - Solution-focused: Add "solved", "fix", "how to" - Experience-focused: Add "experience", "review", "worth it" - Negative signal: "scam", "avoid", "warning" - Historical: Use --provider pullpush for deleted/old content

2. Search and Triage

Run each query. For each result set: - High score + lots of comments = worth reading the thread - Low score but specific = might have niche info - Cross-posted = narrative spreading

3. Read Key Threads

npx tsx reddit.ts thread <url> --sort top --limit 30

4. Cross-Reference

npx tsx reddit.ts duplicates <post_id>

5. Comment Deep Dive

Search through comments when posts don't surface the answer:

npx tsx reddit.ts comments "specific error message" --provider pullpush --limit 20

6. Synthesize

Group findings by theme:

### [Finding/Theme]
[Summary]
- u/username in r/subreddit (⬆️ N): "[key quote]" Link
- u/username2 in r/subreddit2 (⬆️ N): "[another take]" Link

Heartbeat Integration

On heartbeat, run watchlist check to see if watched subreddits have notable activity. Flag only if genuinely interesting/actionable.

Rate Limits

• Reddit JSON: ~60 req/min, User-Agent required, auto-retry with backoff
• PullPush: Generous, no official limit, sometimes down
• Arctic Shift: Generous, no official limit
• Cache: 15min TTL prevents redundant hits

File Structure

skills/reddit-research/
├── SKILL.md                # This file
├── README.md
├── package.json            # Zero dependencies
├── assets/
│   └── banner.svg
├── scripts/
│   ├── reddit.ts           # CLI entry point
│   └── lib/
│       ├── api.ts          # Reddit + PullPush + Arctic Shift wrapper
│       ├── cache.ts        # File-based cache
│       └── format.ts       # Terminal + markdown formatters
├── data/
│   ├── watchlist.json      # Watched subreddits
│   └── cache/              # Auto-managed
└── references/
    └── reddit-json-api.md  # API endpoint reference

Requirements

• Node.js 18+ (for native fetch)
• No API key needed
• No npm install needed — zero dependencies