Lead Researcher

Give your AI coding assistant a job: find you 2,000 qualified leads — and don't stop until it's done.

Lead Researcher is a tiny, open, do-it-yourself sales prospecting worker. You install it once into Claude Code, OpenCode, or Codex CLI. From then on, you just say:

"Get 2000 leads for me based on my ICP and don't stop until it's done."

…and your AI goes to work: researching real people on the public web, checking each one against your Ideal Customer Profile, recording only the ones that pass the quality gate — batch after batch, session after session — until the target number is reached. Progress is saved to disk, so closing your laptop doesn't lose anything: reopen it, say "continue", and it picks up where it left off.

No accounts. No servers. No subscriptions. Your lead data never leaves your computer. Just Python 3 and your AI tool.

---

What you get

🎯 A real target	The goal (2000) is stored in data/state.json — not in chat memory. It survives restarts.
✅ A quality gate	A lead only counts if its score ≥ 70 and the evidence cites your ICP file. No junk padding.
🔁 Continuous work	Batch loop with resume. Say "continue finding leads" any time, in any new session.
📝 One editable ICP	Everything about who counts lives in one human-readable file: icp.md.
📤 Clean export	python3 lr.py export csv → leads.csv, ready for your CRM or spreadsheet.

---

Install (pick ONE — both take under 2 minutes)

Option A · One terminal command

Open Terminal (Mac) or PowerShell (Windows), paste this, press Enter:

curl -fsSL https://raw.githubusercontent.com/ShayanSpiel/Lead-Researcher/main/install.sh | bash

That clones the repo, verifies the installation with a self-test, and prints your next step.

Prefer not to pipe scripts? Do it manually

git clone https://github.com/ShayanSpiel/Lead-Researcher.git ~/Lead-Researcher
cd ~/Lead-Researcher
python3 lr.py selftest

Option B · Let your AI do everything (zero terminal skills)

1. Make sure you have one of these installed and working:
   • Claude Code → claude
   • OpenCode → opencode
   • Codex CLI → codex
2. Open your tool in any empty folder and paste this single message:

Install https://github.com/ShayanSpiel/Lead-Researcher following its AGENTS.md,
then help me write my icp.md, and start finding leads until we hit my target.

That's it. Your AI handles cloning, setup verification, and asks you 3–4 plain questions ("What do you sell? Who buys it? Who should we NOT contact?") to write your ICP.

---

Daily use (after install)

Open Terminal, go to the folder (cd ~/Lead-Researcher), start your AI tool (claude / opencode / codex), then say things like:

You say	What happens
"Continue finding leads until the target is met."	Resumes from saved progress and keeps going
"How many leads so far?"	Runs status, shows progress toward target
"Update my ICP: we also sell to Series B fintech ops leaders."	Rewrites icp.md, confirms with you, continues under the new ICP
"Raise the target to 5000."	Updates the goal on disk
"Export my leads."	Writes leads.csv you can open in Excel/Sheets or import to a CRM

You can also check progress without AI at all:

python3 lr.py status      # progress bar + remaining count

Updating your ICP

Your ICP — the definition of who counts as a lead — lives entirely in icp.md. Two ways to change it:

1. Edit the file yourself in any text editor, or
2. Tell your AI: "Update my ICP: …" — it rewrites the file for you.

Every lead must cite a section of this file as evidence. Change the file, and every future lead follows the new rules automatically. Full guide: docs/ICP-GUIDE.md.

How the research works

The method your AI follows (sources, qualification, evidence rules, batching): docs/LEAD-RESEARCH-METHOD.md. Under the hood: docs/HOW-IT-WORKS.md.

Hands-free mode (the scheduler)

Don't want to keep a chat open? The built-in scheduler runs the worker autonomously: it sleeps, wakes your AI tool headlessly for one research batch every 5 minutes, and repeats until the target is met. No plugins, no servers — a plain loop that drives the tool you already installed.

# inside the repo folder — pick the tool you installed:
python3 lr.py loop --host claude      # Claude Code wakes every 300s
python3 lr.py loop --host codex       # Codex CLI
python3 lr.py loop --host opencode    # OpenCode

# options:
python3 lr.py loop --host claude --interval 600     # wake every 10 min
python3 lr.py loop --host claude --max-batches 20   # stop after 20 batches
python3 lr.py loop --host claude --dry-run          # preview, run nothing

Stop it any time with Ctrl+C — progress is always saved on disk. Keep a normal chat session open too if you like; both share the same data/ state.

Fair use & privacy

• Researches public information only. No scraping behind logins, no paywall bypass, no bulk automated contacting. This tool finds and qualifies; you decide who to contact and how.
• All data stays in this folder. Nothing is uploaded anywhere by this repo.
• Don't use it for anything illegal or spammy. Be the outreach sender you'd want to receive mail from.

FAQ

Does this send emails? No. It builds a verified list. Sending is deliberately out of scope — pair the exported CSV with your own email tool and follow your local anti-spam laws.

What if I close the terminal mid-run? Nothing is lost. Leads are written to disk the moment they're recorded. Reopen and say "continue".

Can I use multiple sessions at once? Run them one at a time; the engine appends safely but parallel writers can race. Sequential batches are the intended mode.

LinkedIn & X specifically? That's the sibling worker: Social Lead Researcher — same pattern, specialized in people on LinkedIn/X, and it enforces a recent public signal so your list is warm.

My own ICP data — private? Yes. data/ and leads.csv are gitignored. Never committed, never synced by us.

What does it cost? This repo is free. Your AI tool usage applies its own pricing/limits.

---

MIT licensed. Built by Shayan Spiel — the same worker pattern that runs SpielOS's own outbound research pipeline.