redditrs

README

redditrs

An agent-optimized CLI for Reddit research using a web-session cookie, no API keys.

Installation

Install the latest release with a single command (macOS / Linux):

(
	tmp="$(mktemp)" || exit 1
	trap 'rm -f "$tmp"' 0
	curl -fsSL https://raw.githubusercontent.com/jhartum/redditrs/main/install.sh -o "$tmp" || exit 1
	sh "$tmp"
)

The script is fully downloaded first (and cleaned up on exit); sh only runs if curl succeeded, so a truncated download never reaches the installer. The installer downloads the release archive and its SHA-256 checksum, verifies the archive before extracting anything, and installs to a secure, user-owned directory already on your PATH (~/.local/bin, ~/bin, /opt/homebrew/bin, /usr/local/bin, or another absolute PATH entry). It rejects directories writable by group or other users. If no suitable directory exists, it creates ~/.local/bin and prints the exact export PATH=... line — it never uses sudo and never edits your shell profile.

Prefer to inspect before running:

curl -fsSLO https://raw.githubusercontent.com/jhartum/redditrs/main/install.sh
less install.sh
sh install.sh
rm install.sh

Options (env VERSION / BINDIR act as defaults, CLI flags override):

# pick a specific version (v1.0.0, 1.0.0, or latest) and install dir
(
	tmp="$(mktemp)" || exit 1
	trap 'rm -f "$tmp"' 0
	curl -fsSL https://raw.githubusercontent.com/jhartum/redditrs/main/install.sh -o "$tmp" || exit 1
	sh "$tmp" -v v1.0.0 -b "$HOME/.local/bin"
)

With Go 1.23+

go install github.com/jhartum/redditrs/cmd/redditrs@latest

go install writes the binary to $GOBIN, or to $GOPATH/bin when GOBIN is unset. Make sure that directory is on your PATH:

GO_BIN="$(go env GOBIN)"
[ -n "$GO_BIN" ] || GO_BIN="$(go env GOPATH)/bin"
export PATH="$GO_BIN:$PATH"

Persist the final export PATH=... line in your shell profile (for example, ~/.zshrc on macOS).

From a checkout (release build — strips debug info and source paths):

make build          # redditrs binary, ~7 MB
# or: go build -trimpath -ldflags="-s -w" -o redditrs ./cmd/redditrs

Cookie

Step-by-step walkthrough (browser → cookie → config → verify): docs/cookie.md.

Pass the cookie of a logged-in Reddit web session via REDDITRS_COOKIE or a file:

export REDDITRS_COOKIE='reddit_session=...; token_v2=...'

Or create ~/.config/redditrs/config.json:

{"cookieFile":"/home/user/.config/redditrs/cookie.txt"}

Priority: REDDITRS_COOKIE → REDDITRS_COOKIE_FILE → cookie in JSON → cookieFile in JSON. The cookie is re-read before every HTTP request. Keep the config and cookie file with 0600 permissions and don't commit them.

The cookie is full access to the account. Using a cookie for programmatic .json reads may conflict with Reddit's terms and carries a risk of account blocking; use a throwaway account at your own risk.

Commands

redditrs                                      # agent home view
redditrs status
redditrs search "claude code vs opencode" --limit 8
redditrs thread 1abc234 --top 10
redditrs pack "comfyui settings for low VRAM" --intent settings
redditrs resolve-subreddits "local LLM" --limit 15
redditrs subreddits "Claude Code"
redditrs trends LocalLLaMA --sort hot
redditrs url-extract https://www.reddit.com/r/ClaudeCode/comments/1abc234/

By default stdout uses TOON output optimized for agents; --format json is available for pipes. Long fields can be expanded with --full, extra list fields with --fields. resolve-subreddits expands multi-term topics internally and returns ranked titles/descriptions in one call. Errors are also structured in stdout; exit codes: 0 success, 1 runtime error, 2 usage error.

Settings

Variable	Default
REDDITRS_CONFIG_PATH	~/.config/redditrs/config.json
REDDITRS_CACHE_DIR	~/.cache/redditrs
REDDITRS_CACHE_PATH	$REDDITRS_CACHE_DIR/reddit.db
REDDITRS_USER_AGENT	redditrs/1.0 personal-use (https://www.reddit.com/.json)
REDDITRS_DELAY_MS	1200 (minimum 250, shared across CLI processes through the bbolt cache)
REDDITRS_CACHE_TTL_MS	3600000
REDDITRS_THREAD_TTL_MS	21600000
REDDITRS_SUBREDDIT_TTL_MS	604800000
REDDITRS_TOPIC_TTL_MS	2592000000

REDDITRS_BASE_URL is supported for local test HTTP servers and defaults to https://www.reddit.com.

Agent skill

redditrs is self-documenting for agents (help[N]: hints at the end of every output, --help on every command). For agents with skill support (pi, Claude Code), the repository ships a ready-made skill — skills/redditrs/SKILL.md: direct command selection by intent, evidence-aware follow-ups, and explicit completion criteria.

Install it via a symlink so the skill always matches the CLI version:

ln -s "$(pwd)/skills/redditrs" ~/.pi/agent/skills/redditrs    # pi
ln -s "$(pwd)/skills/redditrs" ~/.claude/skills/redditrs      # Claude Code

When CLI commands or intents change, update skills/redditrs/SKILL.md — the skill version equals the CLI version.

Development

make test   # or: go test ./...
make vet    # or: go vet ./...
make build  # optimized release binary (stripped, trimmed paths)

The full specification lives in docs/spec.md.

License

MIT License — see LICENSE.

Copyright (c) 2026 Alexandr Brezgunov