Codex-native Lead Hunter

Open-source AI lead generation agent for Codex. Find prospects, research companies, score leads, generate personalized outreach, and create Mail.app drafts — with a human approving every send.

Runs locally · uses your own API keys · DeepSeek-first · Codex / Claude Code / Cursor compatible · Chrome-assisted lead verification · macOS Mail.app draft generation · human approval before every send · no spam, no black-box SaaS.

中文简介：开源 Codex 自动获客 Agent：本地运行，DeepSeek 驱动，自动找客户、评分、写邮件草稿,发送前人工确认。

Why this exists

Most "AI SDR" tools are closed-source SaaS: your product data, your prospect list, and your API keys all live on someone else's server, and outreach fires automatically the moment a lead clears some invisible threshold. Codex-native Lead Hunter takes the opposite bet:

Local-first. The agent runs on your machine against your own LLM/API keys. Lead data never has to leave it.
Codex-native. It's built to be driven by an agentic coding assistant (Codex, Claude Code, Cursor) through a documented Skill and CLI, not just clicked through a dashboard.
Human-in-the-loop by construction. Every outbound action — an email, a comment, a DM — stops at a draft. Nothing sends itself. See the Safety Model below.
Evidence over guesses. Every lead is backed by a source URL you can open and check yourself, not a scraped list with no paper trail.

Features

Multi-agent discovery pipeline — Insight → KeywordGen → Search → LeadExtract → Evaluate, orchestrated with LangGraph, iterating rounds until your target lead count or quality threshold is hit.
DeepSeek-first, provider-agnostic — ships configured for DeepSeek out of the box; swap in OpenAI, Anthropic, OpenRouter, Groq, GLM, Moonshot, MiniMax, or a local Ollama model via one env var (LiteLLM under the hood).
Lead scoring — every lead gets business_value, urgency, fit_score, confidence, a recommended_action, and cited evidence. Only fit_score >= 7 leads enter the outreach queue.
Codex Skill + CLI (lead-hunter) — run hunts, inspect leads, generate outreach drafts, and export results from Codex, Claude Code, Cursor, or a plain terminal.
macOS Mail.app drafts — generates a real Mail.app draft (subject, body, recipient) via AppleScript. It is never sent automatically — you review and hit send yourself.
Browser-assisted verification — opens each lead's source URL / company site / social profile so you (or Codex driving your browser) can confirm it's real before it goes anywhere near an outreach queue.
Multi-channel search — Google Search, Google Maps, and B2B directory search feed the pipeline; adaptive scraping per URL type.
Contact discovery — extracts emails, phone numbers, addresses, and social links from crawled pages.
Real-time progress — FastAPI + SSE streams pipeline stage/round progress to the React frontend.
Cost tracking — optional Langfuse integration records LLM cost, tokens, and latency per hunt.

How it works

flowchart LR
    A[React Frontend / lead-hunter CLI] --> B[FastAPI API]
    B --> C[LangGraph Pipeline]
    C --> C1[InsightAgent]
    C --> C2[KeywordGenAgent]
    C --> C3[SearchAgent]
    C --> C4[LeadExtractAgent]
    C --> C5[Evaluate + Score]

    C1 --> D[LiteLLM]
    C2 --> D
    C4 --> D
    D --> D1[DeepSeek / OpenAI / Anthropic / OpenRouter / Groq / GLM / Moonshot / MiniMax / Ollama]

    C3 --> E[Web / Maps / B2B search]
    C4 --> F[Page scraper]

    C5 --> G[Scored leads: fit_score, evidence]
    G --> H[lead-hunter draft-email / mail-draft]
    H --> I[Mail.app draft — human sends]

flowchart TD
    A[Input: website / keywords / target market] --> B[InsightAgent: understand product]
    B --> C[KeywordGenAgent: generate search terms]
    C --> D[SearchAgent: aggregate results]
    D --> E[LeadExtractAgent: extract structured leads]
    E --> F[Evaluate + Score: fit_score, evidence]
    F -->|continue| C
    F -->|done| G[Outreach drafts: email / comment / reply]
    G --> H[Human review]
    H --> I[You send — nothing sends itself]

Quick Start

Requires Python 3.11+, Node 18+, and (optionally) macOS for Mail.app drafts.

git clone https://github.com/yangshun2005/Codex-native-Lead-Hunter.git
cd Codex-native-Lead-Hunter/backend
cp .env.example .env        # then fill in DEEPSEEK_API_KEY (see below)
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn api.app:app --reload --port 8000

In a second terminal, run the frontend (optional — everything is also reachable via the CLI/API):

cd Codex-native-Lead-Hunter/frontend
npm install
npm run dev

Then either open the web UI at http://localhost:3000, or drive it entirely from the terminal / Codex:

cd Codex-native-Lead-Hunter/backend
python -m cli.lead_hunter init
python -m cli.lead_hunter run --product "AI automation agency" --market "dentists in California"
python -m cli.lead_hunter leads list

DeepSeek Setup

DeepSeek is the recommended default provider — cheap, fast, OpenAI-compatible, and works well for both extraction and reasoning steps.

Get a key at platform.deepseek.com/api_keys.

In backend/.env:

LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

LLM_MODEL=deepseek/deepseek-chat
REASONING_MODEL=deepseek/deepseek-reasoner

Start the backend. If DEEPSEEK_API_KEY (or whichever key your LLM_MODEL/REASONING_MODEL needs) is missing, the server logs a clear startup warning telling you exactly which env var to set — it won't fail silently mid-hunt.

Other providers (OpenAI, Anthropic, OpenRouter, Groq, GLM, Moonshot, MiniMax, local Ollama) work the same way — just point LLM_MODEL / REASONING_MODEL at a different provider/model string and set the matching API key. See backend/.env.example for the full list.

Codex Skill Setup

Codex-native Lead Hunter ships a Skill so Codex, Claude Code, or Cursor can drive the whole workflow — create a hunt, inspect leads, generate outreach drafts, open sources for verification, and create Mail.app drafts — without you hand-writing API calls.

# Point your agent's skill/plugin directory at:
skills/codex-native-lead-hunter/SKILL.md

Then just ask your agent things like:

"Use lead-hunter to find AI automation prospects among dentists in California, then draft outreach for anything scoring fit_score >= 7."

The skill will never send an email or post a comment on its own — see SAFETY.md.

macOS Mail.app Drafts

python -m cli.lead_hunter mail-draft --lead-id <id>

This creates a real Mail.app draft — recipient, subject, body, plus the lead id and source URL for traceability — and stops there. Sending requires you to open Mail.app and click Send yourself. If Mail.app isn't available (non-macOS, or Mail.app not configured), the command returns manual_required instead of failing silently. If the lead has no email, it returns needs_input.

Example Workflows

See examples/ for runnable end-to-end scenarios:

local-business-leads/ — AI automation agency prospecting dentists in California.
github-project-prospecting/ — developer tool looking for open-source maintainers to partner with.
reddit-opportunity-finder/ — surfacing people complaining about manual outreach tools (comment drafts only — nothing is auto-posted).
export-to-csv/ — exporting a scored lead list for your CRM.

Human Approval Safety Model

Read the full policy in SAFETY.md. The short version:

No auto-send, anywhere. Email, comments, DMs — everything stops at a draft.
No CAPTCHA, login, or platform permission bypass.
No mass/spam blasting. The scoring gate (fit_score >= 7) and low default batch sizes exist to keep outreach small and personalized.
You are responsible for complying with each platform's terms of service and applicable anti-spam law (e.g. CAN-SPAM, GDPR, PECR) in your jurisdiction.

Roadmap

See ROADMAP.md for the full list. Highlights:

Multi-agent lead discovery pipeline (LangGraph)
DeepSeek-first provider config
lead-hunter CLI
macOS Mail.app draft generation
Lead scoring (fit_score, evidence, etc.)
Native Chrome/Playwright-driven verification (currently: open-in-browser + manual notes)
Reddit/X/LinkedIn draft-comment helpers beyond the example scripts
Windows/Linux outreach-draft equivalent to Mail.app (e.g. .eml export)

Comparison

	Apollo	Clay	Instantly	n8n workflow	Codex-native Lead Hunter
Open source	❌	❌	❌	✅ (workflow only)	✅
Local-first, your data stays put	❌	❌	❌	⚠️ depends on nodes used	✅
Bring your own LLM API key	❌	⚠️ partial	❌	⚠️ depends on nodes used	✅ (DeepSeek-first)
Codex/Claude Code/Cursor-native	❌	❌	❌	❌	✅
Human approval required before send	⚠️ optional	⚠️ optional	⚠️ optional	⚠️ depends on workflow	✅ by default
Pricing	Per-seat SaaS	Per-seat SaaS	Per-seat SaaS	Free (self-hosted)	Free (self-hosted)

Credits

Built on top of the open-source AI_Find_Customer B2B lead-hunting pipeline. See LICENSE for the MIT terms this project is distributed under.

Contributing

See CONTRIBUTING.md. Bug reports, examples, and additional platform integrations (that respect the safety model) are welcome.

Navigation Menu

Uh oh!

Codex-native Lead Hunter

Why this exists

Features

How it works

Quick Start

DeepSeek Setup

Codex Skill Setup

macOS Mail.app Drafts

Example Workflows

Human Approval Safety Model

Roadmap

Comparison

Credits

Contributing

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Codex-native Lead Hunter

Why this exists

Features

How it works

Quick Start

DeepSeek Setup

Codex Skill Setup

macOS Mail.app Drafts

Example Workflows

Human Approval Safety Model

Roadmap

Comparison

Credits

Contributing