LeadSniper

English | 中文文档

LeadSniper analyzes intent signals in publicly visible short-video comments. It searches public content by keyword, classifies comments into high, medium, and low intent, retains high- and medium-intent records for human review, and produces Excel workbooks and a filterable HTML report. High intent is prioritized for manual verification; medium intent enters a review pool.

LeadSniper performs data organization and analysis only. It does not send messages, post comments, or automate any engagement.

Install

Run LeadSniper directly with npx; no global installation is required:

npx --yes leadsniper@latest

The installer detects macOS Apple Silicon or Windows x64, finds supported Agents, and asks where LeadSniper should be installed.

Install into one or more Agents explicitly:

npx --yes leadsniper@latest --agent codex
npx --yes leadsniper@latest --agent claude,codex

Update

Run the installer again to update every detected installation:

npx --yes leadsniper@latest --all --yes

Update a specific Agent:

npx --yes leadsniper@latest --agent codex --yes

Updates replace only the published Skill files, the LeadSniper executable, the standalone setup executable, and the debug browser launcher. Existing configuration, browser profiles, databases, and output data are preserved. Replaced published files are backed up before an update.

Community

Join the LeadSniper WeChat community:

Open the QR code or view the v0.1.0 release

Installer options

--agent <names>  Install into comma-separated Agents
--all            Install into every detected Agent
--yes, -y        Update existing installations without prompting
--dry-run        Show what would change without writing files
--list           Show detected Agents and installation paths
--help, -h       Show help

Supported Agents are Hermes, OpenClaw, Claude Code, and Codex. The original platform-specific installers remain available:

npx --yes leadsniper-mac@latest
npx --yes leadsniper-win@latest

What LeadSniper does

LeadSniper collects publicly visible comments through a normal, authorized browser session and organizes them for human review. It can:

• Check the browser environment and login state.
• Discover public videos by keyword and collect their public comments, including second-level replies.
• Detect explicit requests, transaction intent, and context-specific numeric call-to-action phrases in video context.
• Classify commenters into high, medium, and low intent with local rules, retaining high- and medium-intent users with separate priority levels.
• Collect direct targets — video/note links, creator home pages, share short links, or bare aweme IDs — alongside keyword discovery, sharing global dedup and resume state.
• Enrich retained potential users with publicly visible profile fields.
• Expand recursively from high-intent seed users.
• Generate cleaned Excel data and a filterable HTML report, and package approved customer-facing deliverables.
• Update manual review and follow-up status, and evaluate local intent rules against a labeled workbook.

Intent levels are signals for human review, not confirmed facts about a person. LeadSniper does not send messages, post comments, or automate engagement.

Supported platforms

| Platform | Executable | Setup executable | Debug browser launcher | |---|---|---|---| | Windows x64 | LeadSniper.exe | setup.exe | start_chrome_debug.bat | | macOS arm64 | ./LeadSniper | ./setup | start_chrome_debug.sh |

Requirements

• Node.js 18 or newer and npm 9 or newer (for the npx installer).
• macOS 14 or newer on Apple Silicon (arm64), or Windows 10/11 (x64).
• Microsoft Edge or Google Chrome for browser collection.
• Hermes, OpenClaw, Claude Code, or Codex.
• Redis for the packaged-release license cache; MongoDB is recommended for long-running collection and vocabulary persistence (a local Excel/JSON compatibility path remains when MongoDB is temporarily unavailable).

Intel Mac, Windows ARM64, and Linux are not currently supported.

Getting started

1. Start the debug browser (requires Edge or Chrome): start_chrome_debug.bat on Windows, or bash start_chrome_debug.sh on macOS.
2. Scan the QR code in the opened browser to log in with an authorized account.
3. On first run the packaged release verifies its local license; if the license cache (Redis) is not ready it launches the setup wizard automatically (see “Authorization and first run”). You can also run LeadSniper setup at any time.
4. Open a new Agent session so its Skill list reloads, then ask the Agent to use LeadSniper with your intended keywords and collection limits. Before collection, LeadSniper requires separate choices for model-assisted search-keyword expansion and model-assisted intent-vocabulary generation.

The installed Skill gives the Agent the correct executable path for the current operating system.

Commands

Run the packaged executable directly, or ask your Agent to run these. Replace APP with LeadSniper.exe (Windows) or ./LeadSniper (macOS):

| Task | Command | |---|---| | Environment check | APP check | | Authorized login | APP login | | Collect comments and identify high/medium intent | APP collect "keyword" --expand-keywords yes/no --generate-intent yes/no | | Generate the default target-user report | APP analyze | | Regenerate analysis from all comments | APP analyze --source comments | | Evaluate intent rules | APP evaluate-intent <labeled.xlsx> | | Update manual review status | APP follow-up | | Edit settings or set keywords | APP config / APP config "keyword A,keyword B" | | View the intent vocabulary | APP keywords | | Initialize the configured database | APP init-db | | Import legacy collection files into MongoDB | APP migrate-storage | | Install Redis/MongoDB, configure DeepSeek, and activate | APP setup |

Before every collection run, confirm model-assisted keyword expansion and intent-vocabulary generation separately: the CLI requires --expand-keywords yes/no and --generate-intent yes/no, and the interactive menu asks both explicitly (Enter is never treated as “no”). A yes choice sends keywords to DeepSeek and may consume API quota, reading DEEPSEEK_API_KEY from the .env created by setup; the collection flow never asks for a key in chat. Missing credentials or a failed generation stops collection instead of silently falling back.

Collection options:

• --videos: maximum newly discovered videos per keyword in this run; previously seen IDs do not consume the budget, so later runs continue incremental discovery and history backfill.
• --comments: maximum public comments per video; 0 means all comments currently available to the page.
• --leads: maximum total retained high/medium-intent users.
• --profiles: maximum public profiles collected this run; 0 disables enrichment.
• --depth: recursive discovery depth; 0 disables recursion, omission uses settings.
• --users-per-depth: maximum high-intent discovery seeds per depth; must be positive.
• --sort: latest for newest-first or hot for popularity-first.
• --replies: yes collects the second-level replies under each top-level comment (default follows settings); no collects top-level comments only.
• --replies-per-comment: maximum replies collected per top-level comment; 0 means all.
• --mode: incremental collects only newly discovered videos, backfill keeps paging toward older videos, auto (default) runs incremental first then switches to backfill in the same session.
• --max-runtime: wall-clock budget in minutes for this run; on expiry it checkpoints and stops so a later run resumes. 0 disables the budget.
• --backfill-before: earliest publish-date bound (YYYY-MM-DD) for history backfill; older videos are not backfilled.
• --direct-urls: comma-separated video/note links, creator home pages, share short links, or bare aweme IDs collected in addition to keyword discovery, sharing the same global dedup and checkpoint pipeline.

Authorization and first run

The packaged release (LeadSniper.exe / ./LeadSniper) enforces a local license check at startup. Authorization uses a server-issued RSA-signed token cached in local Redis, with a 40-minute lease renewed automatically while a feature runs. When the server is briefly unreachable but the local lease is still valid, startup is allowed under an offline grace period; otherwise it fails closed.

On first run, if local Redis (the license cache) is not ready, the setup wizard launches automatically; you can also run APP setup explicitly. The wizard:

• Prompts for the DeepSeek API Key and creates/updates .env beside the executable; on a repeated setup, Enter preserves it. Confirmation messages and logs never echo the key.
• Detects and (local only) installs/starts Redis — Memurai Developer via winget on Windows, Homebrew on macOS, apt/dnf/yum on Linux; a remote Redis is never modified.
• Detects and initializes MongoDB — MongoDB Community Server via winget on Windows or the MongoDB Homebrew tap on macOS; on Linux it starts an existing service and explains when the official repository still needs configuring. Remote MongoDB is connection-checked only.
• Verifies Redis has RDB/AOF persistence enabled; authorization is refused if it is not.
• Prompts for the server-issued License Key to activate and bind this machine.

Installing or starting a local Redis/MongoDB service on Windows requires administrator rights; when privileges are insufficient the wizard prints a clear message and exits with code 1, so re-run setup as administrator (connecting to a remote server is unaffected). The .env file, license token, Redis cache, browser profile, and settings are private local state and are never included in a delivery package or committed to Git.

Checkpoint resume

Resume is the default collection behavior, not a separate menu item. MongoDB holds cross-keyword deduplication and global job state; each original keyword group also keeps its own output directory and a migration-period crawl_state.json. At startup the terminal prints whether the task is new or resumed.

The modes change only where the next batch of videos is discovered, not the resume guarantees: auto checks new videos first then backfills older history in the same session, incremental checks new videos and stops after reaching already-seen territory, and backfill continues toward older videos until the date bound, video budget, or runtime limit. Completed videos and persisted comments are never re-collected. Ctrl+C performs a graceful checkpoint and export; a manual interrupt or an empty run still produces the deliverables and never overwrites the previous cleaned workbook or report with blanks.

Captcha and image-post handling

Collection runs in a visible browser, so a mid-run risk-control check never hangs the crawler. When a captcha or verification interstitial appears, LeadSniper handles it in layers: a best-effort automatic solve first; otherwise it pauses and asks you to complete the check once in the browser window, then auto-resumes the same video; if it still cannot pass within the wait window, the video is marked resumable and skipped so the next run retries it (bounded by the per-video retry cap) instead of recording a false “completed” with zero comments.

Image posts (图文) use a different comment layout from videos. LeadSniper locates the comment entry across layouts — a comment tab, a control whose label starts with 评论, a comment icon, or scrolling the note panel — and verifies the list actually opened. If no entry is found, it saves a page diagnostic and treats the post as resumable rather than silently saving zero comments.

Outputs

Each keyword group uses a separate directory. Customer-facing files are:

• all_comment_users.xlsx: every collected commenter and comment, including low intent (with second-level replies, accumulated across runs).
• target_customs.xlsx: high- and medium-intent potential users, ordered with high intent first.
• analysis/target_customs_clean.xlsx: deduplicated and cleaned target data.
• analysis/target_customs_report.html: filterable analysis report.
• deliverables/leadsniper_*.zip: approved workbooks, reports, and redacted run logs only.

Internal working files (per-keyword search, comment, profile, and user-video details, plus crawl_state.json and collection.log) stay in the keyword directory. Browser profiles, settings, authorization files, database state, and runtime JSON are excluded from delivery packages.

Intent interpretation

High intent includes explicit pricing, purchase, registration, appointment, cooperation, and directly relevant material requests, plus clear call-to-action phrases interpreted in video context. Medium intent indicates relevant interest, comparison, or a request to learn more without a clear action commitment. Generic praise, likes or bookmarks, unrelated location questions, negative statements, and low-relevance interactions do not enter the target-user workbook. When one user produces multiple signals, the highest level is kept.

The model only assists in generating intent vocabulary for a keyword; runtime classification is done by local rules. Intent labels are analytical signals for human review, not factual claims about a person's identity or future purchasing behavior.

Safety and privacy

• Use only publicly visible information available through a normal authorized account, device, and business context.
• Follow applicable law, platform terms, privacy obligations, and retention rules; keep keywords and collection limits necessary and proportionate to a defined purpose.
• Never submit API keys, cookies, database credentials, or login profiles in chat; keys live only in the local ignored .env or environment variables.
• Do not use LeadSniper to bypass access controls, verification, or rate limits, and do not target users using sensitive personal information.
• Human review is required before outreach, external use, or business decisions, with appropriate correction or deletion support.

Maintainer commands

npm test
npm run pack:check
npm run release:check

npm publish --workspace packages/macos
npm publish --workspace packages/windows
npm publish --workspace packages/cli

License

LeadSniper is proprietary software. See LICENSE for the applicable terms.