\n\n> Every comment. Every reply. 94% fewer tokens.\n\nAn 800-comment Reddit thread costs ~120K tokens as raw JSON. Lurk delivers the same thread — full depth, every expanded reply — in a fraction of that.\n\nMost Reddit tools fetch top-level comments and stop. The useful stuff is buried 4-5 replies deep. Lurk expands every collapsed branch, resolves every `+N more replies` placeholder, and reconstructs the full comment tree. Then compresses it into compact tab-delimited notation before it reaches your model.\n\n```text\nPost: \"Finally We have the best agentic AI at home\"\n +-- Comment (180 pts)\n | +-- Reply (46 pts) <-- most tools stop here\n | | +-- Reply (34 pts)\n | | +-- Reply (29 pts)\n | | +-- Reply (8 pts)\n | | +-- Reply (20 pts)\n | | +-- Reply (2 pts)\n | | +-- Reply (4 pts)\n | | +-- Reply (1 pt)\n | | +-- Reply (2 pts) <-- lurk gets all of it\n +-- Comment (82 pts)\n | +-- Reply (45 pts) <-- lurk gets all of this too\n | +-- Reply ...\n +-- Comment (60 pts)\n +-- +47 more replies (expanded) <-- and this\n```\n\n**104 of 109 comments. 10 levels deep. Fully automatic.**\n\n## How Token Savings Work\n\nThe Go binary preprocesses everything before tokens reach your model:\n\n1. **Fetch** — Hits Reddit's JSON endpoints, recursively expands every collapsed `more` placeholder\n2. **Extract** — Strips the 50+ unused fields per comment (gildings, awards, flair, metadata) down to 5-6 that matter\n3. **Compress** — Formats into compact tab-delimited notation: `d0 180 Recent-Success-1520 If you can host Kimi 2.5...`\n\nThe result (benchmarked across 12 threads, 452 comments, 6 subreddits):\n\n| Format | Total Tokens | vs JSON | vs Markdown |\n|--------|-------------|---------|-------------|\n| Raw Reddit JSON | 286,425 | — | — |\n| Markdown | 28,993 | -90% | — |\n| **Lurk (compact)** | **16,186** | **-94%** | **-44%** |\n\n**94% fewer tokens than JSON. 44% fewer than Markdown.** Savings scale with thread depth — shallow quips save ~10-25% vs markdown, deep technical threads save 50-64%.\n\n### Smart Comment Limiting\n\nThreads with 200+ comments get a preview first instead of dumping everything:\n\n```text\n#post r/ClaudeAI u/poster 422pts 93% 805cmt 2026-01-28\nFinally We have the best agentic AI at home\n\n#comments 461\nd0 180 Recent-Success-1520 If you can host Kimi 2.5...\n...\n\n#warning 805 total comments, showing 461. Use limit=N for top N by score, or limit=0 for all (~31K tokens).\n```\n\nClaude sees the warning and decides whether to fetch everything or grab the top 50 by score. No surprise 31K-token dumps.\n\n## What You Get\n\n- **Full comment trees** at any depth — every collapsed branch expanded\n- **94% fewer tokens** than JSON, 44% fewer than Markdown\n- **Smart limiting** — large threads preview first, expand on demand\n- **Adaptive caching** — new feeds: 2min, hot: 5min, threads: 10min, top: 30min, 50MB LRU cap\n- **Multi-subreddit search** — comma-separated subs, parallel fetch, deduped results\n- **OAuth support** — optional `lurk auth` for 6x rate limits (60 req/min vs 10)\n- **All URL formats** — reddit.com, old.reddit.com, new.reddit.com, np.reddit.com, redd.it short links, m.reddit.com, amp.reddit.com\n- **Cross-posts** traced to the original\n- **Galleries, video, media URLs** extracted as clickable links\n- **Single Go binary**, zero runtime dependencies\n- **Read-only by design** — no write operations, no account access\n\n## Install\n\n### One-Line Install (Recommended)\n\n**Linux / macOS:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ProgenyAlpha/reddit-lurker/master/install.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://raw.githubusercontent.com/ProgenyAlpha/reddit-lurker/master/install.ps1 | iex\n```\n\nDownloads the binary for your platform and walks you through editor setup. Supports Claude Code, Cursor, Windsurf, VS Code (Copilot), Cline, and Zed.\n\n### Homebrew\n\n```bash\nbrew install ProgenyAlpha/tap/lurk\n```\n\n### npx\n\n```bash\nnpx reddit-lurker\n```\n\nIf you already have Node/npm. Also available on [Smithery](https://smithery.ai).\n\n### Go Install\n\n```bash\ngo install github.com/ProgenyAlpha/reddit-lurker@latest\n```\n\nBuilds from source. Requires [Go 1.24+](https://go.dev/dl/). Run `./install.sh` afterward for editor configuration.\n\n### From Source\n\n```bash\ngit clone https://github.com/ProgenyAlpha/reddit-lurker.git\ncd reddit-lurker\n./install.sh\n```\n\n---\n\nThe installer walks you through editor selection and integration mode.\n\n### Supported Editors\n\n| Editor | Config location | MCP key |\n|--------|----------------|---------|\n| Claude Code | `~/.claude.json` or `~/.claude/skills/reddit/` | `mcpServers` |\n| Cursor | `~/.cursor/mcp.json` | `mcpServers` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |\n| VS Code (Copilot) | `~/.config/Code/User/mcp.json` (Linux) / `~/Library/.../Code/User/mcp.json` (macOS) | `servers` |\n| Cline | VS Code globalStorage (auto-detected) | `mcpServers` |\n| Zed | `~/.config/zed/settings.json` | `context_servers` |\n\nClaude Code also supports a **Skill** mode (~20 tokens overhead vs ~438 for MCP). The installer will ask which you prefer.\n\n### Manual Configuration\n\nAdd lurk to your editor's MCP config:\n\n**Claude Code, Cursor, Windsurf, Cline:**\n```json\n{\n \"mcpServers\": {\n \"lurk\": {\n \"command\": \"lurk\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\n**GitHub Copilot (VS Code):**\n```json\n{\n \"servers\": {\n \"lurk\": {\n \"command\": \"lurk\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\n**Zed:**\n```json\n{\n \"context_servers\": {\n \"lurk\": {\n \"command\": \"lurk\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\n## OAuth (Optional)\n\nLurk works without any authentication. But if you want 6x the rate limit (60 req/min instead of 10):\n\n```bash\nlurk auth\n```\n\nThis opens Reddit's app creation page, walks you through the 5-minute setup, tests your credentials, and saves them. One-time process. Lurk handles token refresh automatically.\n\n```bash\nlurk auth --status # Check if credentials are configured\nlurk auth --clear # Remove saved credentials\n```\n\nYou can also set credentials via environment variables in your MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"lurk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"reddit-lurker\"],\n \"env\": {\n \"LURK_CLIENT_ID\": \"your_client_id\",\n \"LURK_CLIENT_SECRET\": \"your_client_secret\"\n }\n }\n }\n}\n```\n\nOr via a credentials file at `~/.config/lurk/credentials.json`:\n```json\n{\"client_id\": \"your_client_id\", \"client_secret\": \"your_client_secret\"}\n```\n\n## Usage\n\nJust talk to Claude naturally:\n\n- *\"Read this thread\"* + paste a Reddit URL\n- *\"What's trending on r/ClaudeAI?\"*\n- *\"Search r/selfhosted,r/homelab for 'ZFS backup'\"*\n- *\"What has u/spez been up to?\"*\n\nClaude handles the rest. No commands to memorize.\n\n## Real Example\n\nHere's what lurk actually outputs for a [109-comment r/LocalLLM thread](https://www.reddit.com/r/LocalLLM/comments/1qp880l/finally_we_have_the_best_agentic_ai_at_home/) about running Kimi K2.5 at home.\n\n**What most tools give your LLM:**\n```\nu/Recent-Success-1520 (180 pts)\n If you can host Kimi 2.5 1T+ model at home then it tells\n me you have a really big home\n\nu/No_Conversation9561 (82 pts)\n not in my home\n\nu/rookan (60 pts)\n yeah, my 16GB VRAM card can easily handle it /s\n\n... 12 top-level comments, no replies\n```\n\n**What lurk gives your LLM:**\n```\n#post\tr/LocalLLM\tu/moks4tda\t422pts\t93%\t109cmt\t2026-01-28\nFinally We have the best agentic AI at home\n\n#comments\t104\nd0\t180\tRecent-Success-1520\tIf you can host Kimi 2.5 1T+ model at home...\nd1\t46\tHenkPoley\tApparently it's a native 4 bit weights. So \"only\" 640 GB needed...\nd2\t34\tTechnicalGeologist99\tSorry...you're going to run that model on RAM?\nd3\t29\tHenkPoley\t24 tokens per second on 2x 512GB Max Studio M3 Ultra\nd4\t8\tdoradus_novae\tSee you tomorrow when it answers your question\nd5\t20\tScrubbingbubblz\tYou are over exaggerating. 24 tokens per second...\nd6\t2\tInfinite100p\tBut what is the prompt processing speed?\nd7\t4\tMiserable-Dare5090\tIt's GPU inference, on two m3 ultras over TB5...\nd8\t1\tInfinite100p\tHow?\nd9\t2\tEastern-Group-1993\tVia usb-c networking, RDMA.\nd0\t82\tNo_Conversation9561\tnot in my home\nd1\t45\tgonxot\t[image] Maybe it's the same guy lol\nd0\t60\trookan\tyeah, my 16GB VRAM card can easily handle it /s\nd0\t27\tkeypa_\t\"at home\" we probably don't have the same home...\n...\n```\n\n**104 of 109 comments. 10 levels deep. ~3,050 tokens.** The 5 missing are deleted posts Reddit still counts but no longer serves.\n\n## Benchmarks\n\nReal numbers from live Reddit threads:\n\n| Thread | Comments | JSON tokens | MD tokens | Lurk tokens | vs JSON | vs MD |\n|--------|----------|-------------|-----------|-------------|---------|-------|\n| r/ClaudeAI (32c) | 32 | 18,721 | 1,604 | 1,206 | -94% | -25% |\n| r/homelab (32c) | 32 | 19,991 | 1,318 | 961 | -95% | -27% |\n| r/linux (32c) | 32 | 21,746 | 3,081 | 1,416 | -93% | -54% |\n| r/selfhosted (34c) | 34 | 19,874 | 1,949 | 1,288 | -94% | -34% |\n| r/ClaudeAI (36c) | 35 | 20,936 | 2,160 | 1,479 | -93% | -32% |\n| r/LocalLLaMA (36c) | 36 | 19,901 | 1,243 | 1,115 | -94% | -10% |\n| r/selfhosted (37c) | 36 | 20,333 | 1,454 | 1,140 | -94% | -22% |\n| r/selfhosted (40c) | 40 | 22,308 | 1,227 | 1,068 | -95% | -13% |\n| r/ClaudeAI (43c) | 42 | 29,426 | 4,065 | 1,562 | -95% | -62% |\n| r/LocalLLaMA (44c) | 44 | 25,797 | 1,922 | 1,302 | -95% | -32% |\n| r/LocalLLaMA (45c) | 43 | 35,066 | 4,245 | 1,519 | -96% | -64% |\n| r/LocalLLaMA (48c) | 46 | 32,326 | 4,725 | 2,130 | -93% | -55% |\n| **Total** | **452** | **286,425** | **28,993** | **16,186** | **-94%** | **-44%** |\n\nMarkdown savings vs JSON vary by thread verbosity. Lurk's compact notation consistently saves 93-96% vs JSON and 10-64% vs Markdown, with deeper technical threads showing the largest gains.\n\n## Updates\n\nLurk checks for new versions once every 24 hours (background, non-blocking, 3-second timeout). If a newer release exists, you'll see a one-line notice after your command finishes.\n\n```bash\nlurk update # Download and install latest\nlurk update --check # Check only, don't install\n```\n\nIf you installed via npm, brew, or `go install`, `lurk update` will detect that and tell you to use your package manager instead.\n\n### Disable Update Checks\n\n```bash\n# Option 1: environment variable\nexport LURK_NO_UPDATE_CHECK=1\n\n# Option 2: config file\nmkdir -p ~/.config/lurk && echo \"disabled\" > ~/.config/lurk/no-update-check\n```\n\n## Error Handling\n\nLurk fails cleanly with a reason, never with raw HTTP dumps or stack traces:\n\n| Scenario | Error message |\n|----------|---------------|\n| Deleted/nonexistent thread | `not found — check the URL or subreddit name` |\n| Private/quarantined subreddit | `access denied — subreddit may be private or quarantined` |\n| Malformed URL | `not a valid thread URL — expected reddit.com/r/sub/comments/id/title` |\n| Reddit is down | `Reddit server error (HTTP 5xx) — Reddit may be down` |\n| Rate limited | `rate limited — too many requests, try again shortly` |\n\n## Limitations\n\n- **Public content only** (without OAuth). Private and quarantined subreddits require `lurk auth`.\n- **Deleted comments are ghosts.** Reddit counts them in the total but no longer serves content. A \"1,092-comment\" thread may only have ~805 live comments.\n- **No media download.** Media URLs (images, video, galleries) are extracted as clickable links — not downloaded or embedded.\n\n---\n\n## Reference\n\nDetails for the curious.\n\n### CLI Commands\n\n```bash\nlurk thread \"https://reddit.com/r/ClaudeAI/comments/...\" # Full thread + comments\nlurk subreddit ClaudeAI --sort top --time week --limit 10 # Browse\nlurk search \"prompt engineering\" --sub ClaudeAI --limit 5 # Search\nlurk search \"ZFS\" --sub selfhosted,homelab,datahoarder # Multi-sub search\nlurk user spez --limit 5 # User activity\nlurk subreddit ClaudeAI --info # Subreddit metadata\nlurk auth # OAuth setup\nlurk update # Self-update\n```\n\n### Flags\n\n| Flag | What it does | Works with |\n|------|-------------|------------|\n| `--sort` | hot, new, top, rising, controversial, relevance, comments | subreddit, search |\n| `--limit` | Max results (default 25) | subreddit, search, user |\n| `--time` | hour, day, week, month, year, all | subreddit, search |\n| `--sub` | Restrict search to subreddit(s) — comma-separated for multi-sub | search |\n| `--after` | Pagination token for next page | subreddit, search (single-sub only) |\n| `--info` | Subreddit metadata instead of posts | subreddit |\n| `--json` | Raw JSON output | all |\n| `--compact` | Compact notation (default in MCP mode) | all |\n| `--no-cache` | Skip cache | all |\n\n### MCP Tools\n\n| Tool | Purpose |\n|------|---------|\n| `lurk` | Read threads, browse subreddits, search posts, view user activity |\n| `lurk_info` | Get subreddit metadata (subscribers, active users, description) |\n\n### Understanding Skill vs MCP\n\nBoth modes use the same compact notation, so per-call token cost is identical. The differences:\n\n**Context overhead.** Every message you send, Claude also receives hidden tool definitions. Skill adds ~20 tokens. MCP adds ~438 tokens. On subscription plans this is cached and free. On the API, you pay for it every message.\n\n**Caching.** MCP runs as a background server. Its adaptive in-memory cache means hitting the same thread or subreddit twice is instant. Skill starts a fresh process each call — no cross-call cache.\n\n**Permissions.** Skill works through Bash, so Claude needs shell permission. MCP is a native tool call. If you run with Bash restricted, MCP works without it.\n\n### Compact Notation\n\nTab-delimited output designed for LLMs. `d0/d1/d2` = comment depth. Score before author. `+N` = collapsed comments not loaded. `#next` = pagination token. `#warning` = smart limit triggered.\n\n```text\n#post r/ClaudeAI u/BusyBea2 1pts 57% 9cmt 2026-02-23\nEmail and Claude\nHave you figured out how to use Claude to manage your inbox?\n\n#comments 3\nd0 6 Ok-Version-8996 I'm surprised gmail hasn't done this already\nd1 3 BusyBea2 i hear you, that's one of my first clean up things\nd0 2 turtle-toaster Claude Settings lets you connect your Gmail\n```\n\n### Adaptive Cache\n\n| Content | TTL | Rationale |\n|---------|-----|-----------|\n| `/new` feeds | 2 min | Fresh content, stale quickly |\n| `/hot` feeds | 5 min | Changes moderately |\n| Threads & comments | 10 min | Stable once posted |\n| Search results | 10 min | Results shift slowly |\n| User profiles | 15 min | Rarely changes |\n| `/top` feeds | 30 min | Rankings are stable |\n\n50MB LRU cap with automatic eviction. OAuth-authenticated requests use `oauth.reddit.com` automatically.\n\n### Under the Hood\n\n- Appends `.json` to any Reddit URL — no API keys needed for public content\n- Recursively walks comment trees to arbitrary depth\n- Fetches `/api/morechildren` to expand collapsed threads (batched, max 100 IDs per request)\n- Unauthenticated: 10 req/min with burst allowance (100 tokens / 10-min window)\n- Authenticated: 60 req/min (OAuth client_credentials grant)\n- Retries 429/5xx with exponential backoff (3 attempts)\n- Resolves redd.it short links via HTTP redirect\n- Single static Go binary, cross-compiled for linux/darwin/windows amd64/arm64\n\n### Build from Source\n\n```bash\nmake build # Local binary\nmake all # Cross-compile all platforms\nmake install-skill # Install to ~/.claude/skills/reddit/\n```\n\n### Uninstall\n\n```bash\nrm -rf ~/.claude/skills/reddit # Remove skill\nlurk auth --clear # Remove saved credentials\n# For MCP: edit ~/.claude.json, delete \"lurk\" from mcpServers\n```\n\n## License\n\nMIT\n",
"bytes": 17397,
"sha": "f717e0cf9558a0c6b916a32d129fdb75db486656219d4e5526faf5b0a8bdaf0a",
"repo_slug": "progenyalpha/reddit-lurker",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_progenyalpha_lurk_0b495381/readme"
}
![\"Lurker\"](\"assets/lurker.svg\")
\n ![\"Release\"](\"https://img.shields.io/github/v/release/ProgenyAlpha/reddit-lurker\")
![\"Go\"](\"https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go&logoColor=white\"){kind=icon}
![\"License:](\"https://img.shields.io/github/license/ProgenyAlpha/reddit-lurker\")
![\"Platform\"](\"https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey\"){kind=icon}