Snoopy

Monitor online conversations for high-intent signals with AI. Plain language criteria, continuous scanning, zero infrastructure.

📖 Docs · 🇺🇸 English · 🇨🇳 简体中文 · 🇩🇪 Deutsch

Snoopy monitors online conversations for high-intent signals that match your business goals.

Define what you care about in plain language, let Snoopy create a monitoring job, and continuously scan and qualify conversations so you can focus on response and outreach.

Built for founders, marketers, and sales teams who need to find genuine opportunities in online communities without manually scrolling.

Features

• Plain language job creation — Describe what you're looking for in plain language. Snoopy builds an AI-assisted monitoring job. No regex, no keyword configs.
• AI qualification, not keyword matching — Conversations are evaluated against your intent. Snoopy understands context — not just pattern matching.
• Feedback-driven prompt learning — Review results, submit valid/invalid feedback, and consolidate updates so your qualification prompt gets smarter over time.
• Continuous daemon monitoring — Set a cron schedule and let Snoopy scan in the background. snoopy daemon start
• Code-driven efficiency — Deterministic code handles scraping, scheduling, state management, and SQLite persistence. Tokens only spent on qualification.
• Local & private — SQLite database on your machine. No cloud dependency. Export to CSV or JSON on demand.
• Cost-aware analytics — Token usage, cost estimates, and qualified items per run. snoopy analytics --days 7
• Agent & CI ready — MCP server, direct SQLite access, non-interactive mode, machine-readable output.
• Cross-platform — macOS, Linux, Windows. Startup-on-reboot. snoopy startup install

Quick Start

Requirements: Node.js 20+, npm 10+.

npm install -g @telepat/snoopy

1. Create your first monitoring job:

snoopy job add

2. Run a quick test scan:

snoopy job run --limit 5

3. Start the background daemon:

snoopy daemon start

4. View results:

snoopy results
snoopy export --json --last-run

For full onboarding, see Installation & Setup and Quick Start.

Requirements

• Node.js 20+
• npm 10+
• macOS, Linux, or Windows

How It Works

Snoopy uses Reddit public JSON endpoints (with optional OAuth fallback) to scan posts and comments against an AI-assisted qualification prompt. Matches are stored in a local SQLite database. The built-in daemon runs jobs on cron schedules, and results can be exported as CSV or JSON on demand.

Using With AI Agents

Snoopy is built for headless automation and agent-driven monitoring:

• Non-interactive CLI — Most commands support omitting <jobRef> to get an interactive picker, but automation can pass refs directly for zero-prompt execution.
• Machine-readable output — snoopy export --json --last-run and snoopy consume --json produce structured data for downstream agents.
• Feedback loop for continuous quality — Agents can run snoopy feedback review --json, collect human feedback, submit with snoopy feedback submit, and finalize with snoopy feedback consolidate.
• Direct database access — SQLite at ~/.snoopy/snoopy.db (or $SNOOPY_ROOT_DIR/snoopy.db) with a documented schema. Agents can insert jobs, query results, and update lifecycle flags directly.
• Environment variables — TELEPAT_OPENROUTER_KEY, SNOOPY_REDDIT_CLIENT_SECRET, and SNOOPY_ROOT_DIR remove all interactive credential prompts.
• Agent docs — Agent Operations provides a complete runbook for automation, including SQL schema, lifecycle flags, and recommended workflows.

Feedback Workflow

Use the feedback commands to improve qualification quality over time:

# 1) Review unvalidated qualified results (agent-safe JSON)
snoopy feedback review --json --limit 10

# 2) Submit per-result feedback
snoopy feedback submit <resultId> --valid
snoopy feedback submit <resultId> --invalid --reason "Not actually a buying signal"

# 3) Consolidate feedback into an updated qualification prompt
snoopy feedback consolidate

Interactive snoopy feedback review sessions also prompt to run consolidation before exiting early.

Security And Trust

• Secrets are stored in the OS keychain by default (via keytar). Falls back to an encrypted file if keychain is unavailable.
• Environment variables override stored secrets and are recommended for CI and containerized environments.
• Reddit OAuth credentials are optional; public JSON endpoints are used by default.
• Run logs older than 5 days are deleted automatically.

To report a security issue, open a private report through the repository security flow.

Documentation And Support

• Documentation site
• Installation & Setup
• Quick Start
• CLI Reference
• Agent Operations
• Scheduling & Daemon
• Security
• Repository
• npm package

Contributing

Contributions are welcome. See Development for setup, workflow, and quality gates.

License

MIT. See LICENSE.