reddit-reading

1---2name: reddit-reading3description: "Read Reddit: subreddits, search, threads, users. No browser."4version: 1.0.05author: Teknium (teknium1), Hermes Agent6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [Reddit, Social Media, Research, Discussions, Community]11    related_skills: [rss-feeds, grounded-citations, blocked-page-recovery, xurl]12---13 14# Reddit Reading Skill15 16Reads Reddit content — subreddit listings, site or subreddit search, full threads with17comments, and user activity — from a server or headless machine where the normal routes18are dead. It does not post, vote, or log in as a user. Idea credit: the per-platform19backend routing in [Agent Reach](https://github.com/Panniantong/Agent-Reach).20 21## When to Use22 23- "What is r/LocalLLaMA saying about X", "find Reddit threads on Y", "summarise this24  Reddit thread", "what has u/someone posted lately".25- Any `reddit.com` URL the user shares. `web_extract`, `browser_navigate` and the26  `.json` endpoints all fail from server IPs (403 or a "Prove your humanity" wall);27  this skill is the working path.28- Not for posting, voting, messaging, or anything needing a user login.29 30## Prerequisites31 32**None.** No Reddit account, login, cookie, or API key is needed. The default backend is33Reddit's public Atom feeds (`.rss` endpoints), the only unauthenticated route Reddit still34serves to non-residential IPs. It is throttled to about one request per minute per IP and35returns thinner data (no scores, top-level comments only), which is fine for a few calls.36 37**Optional upgrade (app credentials, still no user login):** for sustained use or full38data, register a free "script" type app at https://www.reddit.com/prefs/apps and put its39two values in `~/.hermes/.env`:40 41```42REDDIT_CLIENT_ID=...43REDDIT_CLIENT_SECRET=...44```45 46This is an application registration, not a login: the script uses the app-only47`client_credentials` grant, never a username, password, or browser cookie, and never48acts as the user. With both values set it switches to the OAuth API automatically49(~100 requests per minute, scores, nested comments, `num_comments`); if they are50missing or rejected it falls back to the anonymous feeds and says so on stderr.51 52| | Anonymous feeds (default) | OAuth app credentials |53|---|---|---|54| Setup | nothing | 1-minute app registration, two `.env` values |55| Rate limit | ~1 request / minute / IP | ~100 requests / minute |56| Thread data | post + top-level comments, no scores | nested comments, scores, comment counts |57| Acts as a user | no | no |58 59## How to Run60 61Run every command through `terminal` with the skill-relative script path:62 63```bash64python3 scripts/reddit.py doctor                                  # which backend, current rate-limit window65python3 scripts/reddit.py sub LocalLLaMA --sort hot --limit 1566python3 scripts/reddit.py search "hermes agent" --sub LocalLLaMA --sort new67python3 scripts/reddit.py thread https://www.reddit.com/r/x/comments/abc123/slug/ --limit 4068python3 scripts/reddit.py user spez --limit 1069python3 scripts/reddit.py --json search "topic"                  # machine-readable70```71 72## Quick Reference73 74Every command works on both backends; the script chooses the backend, you never pass a flag.75 76| Need | Command | Anonymous | OAuth |77|---|---|---|---|78| Subreddit front page | `sub NAME --sort hot\|new\|top\|rising [--time week]` | ✔ | ✔ |79| Search all of Reddit | `search "q" --sort relevance\|new\|top\|comments` | ✔ | ✔ |80| Search one subreddit | `search "q" --sub NAME` | ✔ | ✔ |81| Thread + comments | `thread URL --limit N` | ✔ top-level only, no scores | ✔ nested, scores |82| User posts/comments | `user NAME` | ✔ | ✔ |83| Backend + rate limit | `doctor` | ✔ | ✔ |84 85## Procedure86 87① `doctor` once per task if you have not called it this session — it tells you which88backend is live and how many seconds remain in the anonymous window.89 90② Plan your calls before making them. Anonymous Reddit allows roughly **one request per91minute per IP**; the script sleeps until the window resets on a 429 and retries once, so92a five-call plan costs about five minutes. Prefer one `search --sub` over several `sub`93listings, and read one thread rather than the whole listing.94 95③ For "what is the community saying" questions, read the thread bodies (`thread`) rather96than stopping at titles; the listing only carries the first ~300 characters of each post.97 98④ Cite the permalink (`url` field), not the listing page, when the result feeds a report.99`grounded-citations` registers these URLs like any other source.100 101⑤ If the user needs sustained Reddit access (monitoring, more than ~10 calls), stop and102ask them to register the app credentials (Prerequisites) rather than grinding through the103throttle. Tell them plainly: it is a free app registration, not logging Hermes into their104account. Never ask for a Reddit password or browser cookies.105 106## Pitfalls107 108- `www.reddit.com/…/.json`, `api.reddit.com` and `old.reddit.com` return 403 or an109  empty "Welcome to Reddit" shell for datacentre IPs. Do not fall back to them; do not110  spoof a browser User-Agent (also 403).111- `r.jina.ai` and the `browser_navigate` tool hit the same block ("blocked by network112  security" / humanity check). `blocked-page-recovery`'s Wayback route can still recover113  an **old** thread that was archived; it cannot fetch fresh ones.114- Anonymous thread feeds only contain the post plus top-level comments (Reddit caps the115  feed at a handful of entries); scores and reply nesting are OAuth-only.116- Reddit's `limit` on feeds is advisory — expect 5–25 entries regardless of what you ask.117- Never paste `REDDIT_CLIENT_SECRET` into a chat or log; the script reads it from the118  environment only.119- Do not "fix" a 429 by retrying in a loop or adding a proxy; the throttle is per IP and120  the script already waits out the window once. More than one 429 in a row means the121  task needs the app credentials.122 123## Verification124 125`python3 scripts/reddit.py doctor` prints `anonymous_feed: ok` and an126`x-ratelimit-reset` value; `sub announcements --limit 1` returns one entry with a127`reddit.com/r/announcements/comments/` URL. With credentials set, `doctor` prints128`active_backend: oauth` and `thread …` output shows numeric scores.129