reddit-search

Agent-first CLI for researching Reddit. Wraps Reddit's public JSON API (no auth required), normalizes responses, caches aggressively, handles rate limits, and ships with a SKILL.md so AI coding agents (Claude Code, etc.) can use it out of the box.

Why

WebFetch and WebSearch hit Cloudflare interstitials on Reddit, return HTML that wastes tokens, and don't paginate or traverse comment trees. reddit-search gives an agent (or a human) clean JSON for:

• Searching Reddit (site-wide or scoped)
• Browsing a subreddit's hot / new / top / rising / controversial
• Fetching a post with its comment tree
• Pulling a user's profile and recent activity
• Discovering relevant subreddits for a topic
• Multi-subreddit research aggregation in one call
• Velocity-sorted "trending right now" detection
• Pain-keyword mining for SaaS pain-point discovery

Install

Requires Python 3.11+ and uv (or pipx).

git clone git@github.com:muneebhashone/reddit-search.git
cd reddit-search
uv tool install .

Verify:

reddit-search --version
reddit-search --help

Install the agent skill

Install from skills.sh:

npx skills add muneebhashone/reddit-search

Or print the bundled SKILL.md and drop it into Claude Code's skills directory:

reddit-search skill > ~/.claude/skills/reddit-search.md

(For any other skill-aware agent, follow that agent's install procedure with the same file.)

Usage

All commands emit a single JSON object to stdout. Errors go to stderr with a non-zero exit code. Add --pretty to indent for humans.

# search the whole of Reddit
reddit-search search "claude code" --time week --limit 25

# browse a subreddit's hot posts
reddit-search subreddit python --sort hot --limit 20

# fetch a post and its comment tree
reddit-search post https://reddit.com/r/python/comments/abc123/title/ --comment-sort top --comment-limit 50

# discover which subreddits cover a topic
reddit-search discover "AI agents" --limit 10

# one-call multi-subreddit research (discover + search + aggregate)
reddit-search research "MCP servers" --max-subs 5 --posts-per-sub 10 --time month --pretty

# what's trending right now in a subreddit (velocity-sorted)
reddit-search trending r/python --window 6h --limit 20

# mine for pain points across discovered subs
reddit-search pain-points --topic "video editing" --time month --limit 50 --include-comments

Global flags

Must come before the subcommand:

Flag	Effect
--pretty	Pretty-print JSON (2-space indent)
--no-cache	Force-refresh, bypass cache for this call
-v / --verbose	Log cache hits and HTTP activity to stderr
--version	Print version and exit

Cache

On-disk cache at ~/.cache/reddit-search/ via diskcache. Per-endpoint TTLs (hot lists: 5 min; posts: 1 h; discovery: 24 h). Inspect or wipe:

reddit-search cache stats
reddit-search cache info
reddit-search cache clear

Limits (unauthenticated)

Reddit's public JSON API limits us to:

• ~60 requests/minute per IP (the CLI auto-throttles).
• Pagination caps at ~1000 items per listing (Reddit hard limit).
• "Load more" comment stubs can't be expanded (we surface them in comment_stats.expandable_stubs so you know what's missing).

Enabling OAuth (below) raises the rate to ~100/min and auto-expands the stubs.

Optional: OAuth

The CLI works fully unauthenticated. Adding OAuth unlocks:

• ~100 req/min instead of ~60.
• Automatic expansion of "load more" comment stubs (so post / comments return full threads).
• (Tier 2 only) user-context endpoints and access to private subreddits the user belongs to.

Two tiers, auto-detected at every invocation:

Tier	Trigger	Setup
1. App-only	REDDIT_CLIENT_ID + REDDIT_CLIENT_SECRET env vars	Create a Reddit script app, copy the two values into env
2. User-context	Tier 1 + reddit-search auth login	One-time browser flow; refresh token stored in OS keyring

Quick check:

reddit-search auth status        # which tier am I on right now?
reddit-search auth test          # actually call Reddit and report ok/fail
reddit-search auth login         # interactive browser flow for Tier 2
reddit-search auth logout        # delete the stored refresh token

Full step-by-step (Reddit app creation, redirect URI, troubleshooting):

reddit-search skill oauth-setup

The redirect URI on your Reddit script app must be exactly:

http://127.0.0.1:65010/callback

When auth is active, post and comments auto-expand stubs up to --expand-limit N (default 200 hidden comments). Use --no-expand to keep stubs.

For full design rationale and ecosystem-aware best practices, see the bundled docs:

reddit-search skill                      # main SKILL.md
reddit-search skill api-quirks           # Reddit JSON shape reference
reddit-search skill research-strategies  # research-flow recipes
reddit-search skill oauth-setup          # optional OAuth setup

Development

uv sync --extra dev
uv run pytest

License

MIT.