┌─┐┌┐┌┌─┐┌─┐┌─┐┬ ┬
└─┐││││ ││ │├─┘└┬┘
└─┘┘└┘└─┘└─┘┴ ┴
Snoopy helps you monitor Reddit for high-intent conversations that match your business goals.
Define what you care about in plain language, let Snoopy create a monitoring job, and continuously scan and qualify posts/comments so you can focus on response and outreach.
- Turn broad Reddit traffic into a focused stream of opportunities.
- Define qualification logic once, then run continuously.
- Trigger manual runs when you want quick validation.
- Track run analytics (discovered/new/qualified items, token usage, cost estimate).
- Run cross-platform with startup-on-reboot support.
- Interactive job creation flow from natural-language criteria.
- AI-assisted clarification and job spec generation.
- Qualification against your prompt for posts (and comments when enabled).
- Local SQLite persistence for jobs, runs, and scan items.
- Built-in daemon for scheduled scanning (cron expressions).
- On-demand CSV export of qualified results per job.
- Startup registration for macOS, Linux, and Windows.
- Health checks via the doctor command.
Requirements:
- Node.js 20+
- npm 10+
From npm:
npm install -g snoopy-cli
snoopy --helpFrom source:
npm install
npm run build
npm linkFor first-time onboarding (OpenRouter key setup, first job add, and verification), see Installation & Setup.
Run without a global install (contributors):
npm run dev -- --helpCore validation commands:
npm run lint
npm run build
npm testTo refresh coverage locally:
npm test -- --coverageVersioning and changelogs are managed automatically by release-please.
How it works:
- Merge commits to
mainfollowing Conventional Commits (fix:,feat:,feat!:, etc.). - release-please maintains an open "Release PR" that accumulates version bumps and CHANGELOG entries.
- Merge the Release PR to cut a release:
package.jsonversion is bumped,CHANGELOG.mdis updated, a git tag is created, and the package is published to npm automatically.
Commit types and semver mapping (while version < 1.0.0):
fix:→ patch bumpfeat:→ patch bump (minor bump is suppressed pre-1.0)feat!:orfix!:(breaking change) → minor bump (major bump is suppressed pre-1.0)
No manual git tag or npm version steps are needed.
Note:
- Snoopy uses Reddit public JSON endpoints by default.
- Optional Reddit OAuth fallback credentials can be configured in
snoopy settingsfor environments where unauthenticated access is blocked. snoopy settingsshows a full settings menu so you can jump directly to any setting and save once.
- Start interactive setup and create your first job:
snoopy job addjob add now runs an immediate first scan after saving the job so you can validate results right away.
Snoopy pauses scheduled scans for that new job during this first run attempt, then enables scheduling when it ends (including interruption/failure cases).
- List jobs:
snoopy jobs list- Run one job immediately (limit to 5 new items while testing):
snoopy job run --limit 5
snoopy job run <jobRef> --limit 5If <jobRef> is omitted for job run, job enable, job disable, job delete, start, stop, or errors, Snoopy shows your job list and lets you pick with up/down arrows and Enter.
- View run history:
snoopy job runs <jobRef>- View analytics globally or for one job:
snoopy analytics
snoopy analytics <jobRef>
snoopy analytics --days 7- Regenerate results CSV files (all jobs or one job):
snoopy export csv
snoopy export csv <jobRef>- Inspect one run's detailed log output:
snoopy logs
snoopy logs <runId>
snoopy logs <runId> --rawWhen runId is omitted for logs, Snoopy first prompts for a job, then prompts for a run from that job (up/down arrows + Enter).
- Show recent errors for one job:
snoopy errors <jobRef>- Enable daemon mode:
snoopy daemon start
snoopy daemon reloadjob addjob listjob run [jobRef] --limit <N>job runs [jobRef]analytics [jobRef] --days <N>export csv [jobRef]logs [runId]errors [jobRef] --hours <N>start [jobRef]/stop [jobRef]delete [jobRef]daemon start|stop|statusdaemon reloadstartup statusdoctor
- Each job run writes a dedicated log file under
~/.snoopy/logs/. - Files are named
run-<runId>.log. snoopy logsnow supports guided selection (job first, then run) and shows a pretty timeline by default with post/comment text snippets, qualification result + justification, and clickable post/comment links.- Use
snoopy logs [runId] --rawto print the full raw log file content, including full JSON request/response payloads for Reddit and OpenRouter calls. - Rich TTY manual runs (
snoopy job run <jobRef>) show compact multi-line scan blocks with indented fields, clickable links, and qualification justifications. - In rich terminals, scan field labels are colorized and qualification status is highlighted (
qualifiedin green,not qualifiedin red,pendingin yellow). - Run logs older than 5 days are deleted automatically on daemon startup and after each job run.
- Deleting a job also deletes all associated per-run log files for that job.
- Export files are generated on demand with
export csv. - Files are written under
~/.snoopy/results/. - Each job gets one file named
<job-slug>.csv. - CSV files are regenerated from database truth on each export command.
- Deleting a job also deletes that job's CSV file.
Use the built-in smoke harness to verify create -> run(5) -> delete:
npm run e2e:smokeOptional env vars:
SNOOPY_E2E_LIMIT(default5)SNOOPY_E2E_SUBREDDITS(defaultstartups,entrepreneur)SNOOPY_E2E_KEEP_JOB=trueto skip cleanup for debugging
- Documentation Index
- Installation & Setup
- Command Reference
- Database Schema
- Agent DB Operations
- Scheduling, Cron, Daemon, and Startup
- Security and Secret Storage
- E2E Smoke Testing Guide
Serve the Docusaurus docs site locally:
npm run docs:startBuild and preview the static docs site:
npm run docs:build
npm run docs:serveDeploy to GitHub Pages:
GITHUB_OWNER=cozymantis GITHUB_REPO=snoopy npm run docs:deployDocs changes pushed to main under docs/ or website/ are also rebuilt and published to GitHub Pages automatically via GitHub Actions.