š agent-toolclaude-codecodex
163K
skills
Skills for Real Engineers. Straight from my .claude directory.
Mmattpocockabout 12 hours ago
npx skills@latest add mattpocock/skillsDescribe your product. Define your target market. The AI finds the leads and emails them for you.
Demo:
š What is OpenOutreach?
OpenOutreach is a self-hosted, open-source, email-first AI sales agent for B2B lead generation. It discovers leads from a licensed data provider, qualifies them on your own machine, and runs agentic email outreach from a mailbox you own ā with zero platform-ToS surface: it is browserless, uses no social-network account, and does no scraping. Unlike other tools, you don't need a list of profiles to contact ā you describe your product and your target market, and the system autonomously discovers, qualifies, and emails the right people.
How it works:
- You provide a product description and a campaign objective (e.g. "SaaS analytics platform" targeting "VP of Engineering at Series B startups")
- An LLM turns that into an ICP filter and pages matching firmographic profiles from a licensed discovery source (BetterContact Lead Finder) ā no emails yet, billed nothing
- A Bayesian ML model (Gaussian Process Regressor on profile embeddings) learns which profiles match your ideal customer ā an explore/exploit strategy balancing finding the best leads now vs. learning what makes a good lead
- An LLM classifies each candidate the model selects; the GP learns from every decision to pick better candidates over time
- Only the best-fit leads get a paid email lookup. A confidence gate rations a work-email resolution (one credit per verified hit); a hit routes the lead into agentic email ā an AI agent sends a personalized opener from your mailbox, then reads replies and runs multi-turn follow-up
The system gets smarter with every decision: it explores broadly, then progressively focuses on the highest-value profiles as it learns your ideal customer profile from its own classification history.
Why choose OpenOutreach?
- š§ Autonomous lead discovery ā No contact lists needed; AI finds your ideal customers from licensed data
- š§ Email-first outreach ā Resolves a work email per qualified lead and sends from your own mailbox, at email volume
- š”ļø Zero platform-ToS surface ā Browserless, no social-network account, no scraping ā nothing to get banned
- š¾ Self-hosted + full data ownership ā Everything runs locally; browse your CRM in a web UI
- š³ One-command setup ā Dockerized deployment, interactive onboarding
- āØ AI-powered messaging ā LLM-generated personalized outreach and agentic replies (bring your own model)
Perfect for founders, sales teams, and agencies who want powerful automation without account bans or subscription lock-in.
š What You Need
| # | What | Example |
|---|---|---|
| 1 | An LLM API key | OpenAI, Anthropic, or any OpenAI-compatible endpoint |
| 2 | An email-finder API key (BetterContact) | Powers both discovery (Lead Finder) and enrichment (work-email resolution) |
| 3 | A sending mailbox | An app password for a mailbox you own (Gmail / Workspace / own-domain SMTP), or cold-email infra like IceMail |
| 4 | A product description + target market | "We sell cloud cost optimization for DevOps teams at mid-market SaaS companies" |
That's it. No social-network account, no spreadsheets, no lead databases, no scraping setup. The BetterContact key and a connected mailbox are both required ā the key drives discovery and enrichment, and the mailbox is where outreach is sent from.
ā” Quick Start (Docker ā Recommended)
Pre-built images are published to GitHub Container Registry.
docker run --pull always -it -v ~/.openoutreach/data:/app/data ghcr.io/eracle/openoutreach:latest
The interactive onboarding walks you through the inputs above on first run ā product/objective ā LLM key (live-verified) ā mailbox (paste an app password ā SMTP auth-check) ā BetterContact key ā your email ā country ā newsletter/legal. All data persists in ~/.openoutreach/data on your host across restarts. The image is a slim Python runtime ā no browser, no VNC.
For Docker Compose, build-from-source, and more options see the Docker Guide.
āļø Local Installation (Development)
For contributors or if you prefer running directly on your machine.
Prerequisites
1. Clone & Set Up
git clone https://github.com/eracle/OpenOutreach.git
cd OpenOutreach
# Install deps, run migrations, and bootstrap CRM
make setup
2. Run the Daemon
make run
The interactive onboarding prompts for your LLM key, mailbox, BetterContact key, and campaign details on first run. Fully resumable ā stop/restart anytime without losing progress.
3. View Your Data (CRM Admin)
OpenOutreach includes a full CRM web interface via Django Admin:
# Create an admin account (first time only)
python manage.py createsuperuser
# Start the web server
make admin
Then open:
- Django Admin: http://localhost:8000/admin/
āØ Features
| Feature | Description |
|---|---|
| š§ Autonomous Lead Discovery | No contact lists needed ā an LLM turns your product + objective into an ICP filter and pages matching profiles from a licensed discovery source. |
| šÆ Bayesian Active Learning | Gaussian Process model on profile embeddings learns your ideal customer via explore/exploit, selecting the most informative candidates for LLM qualification. |
| š Licensed Discovery | Firmographic profiles come from a paid, licensed provider (BetterContact Lead Finder) ā no scraping, no browser, no account. |
| š§ Agentic Email Outreach | Resolves a work email per best-fit lead (one credit per hit), sends an AI-written opener from your own mailbox over SMTP, then reads replies (IMAP) and runs multi-turn follow-up. |
| š Stateful Pipeline | Tracks deal states (QUALIFIED ā READY_TO_FIND_EMAIL ā FINDING_EMAIL ā READY_TO_EMAIL ā EMAILED ā COMPLETED/FAILED) in a local DB ā fully resumable. |
| ā±ļø Send-Gated Spend | Paid email lookups ride on send capacity ā a per-mailbox daily cap bounds how many leads enter the pipeline, so you never resolve more than you can send. |
| š¾ Built-in CRM | Full data ownership via Django Admin ā browse Leads, Deals, and conversations. |
| š³ One-Command Deployment | Dockerized setup with interactive onboarding; a slim runtime with no browser and no VNC. |
| āļø AI-Powered Messaging | Agentic multi-turn follow-up conversations ā the AI agent reads the thread, composes replies, and schedules future follow-ups. |
š How the Pipeline Works
The daemon runs a continuous task queue backed by a persistent Task model. Four task types self-schedule follow-on work:
| Task Type | What it does |
|---|---|
| find_email | Submits a work-email lookup for a ranked, qualified lead ā a free hub-cache hit resolves immediately; otherwise it fires a paid provider job and parks the deal at FINDING_EMAIL. |
| collect_email | Polls the in-flight lookup (self-chaining backoff): hit ā READY_TO_EMAIL, miss ā FAILED (blank outcome, ML-skipped), couldn't-run/timeout ā back to the queue. |
| follow_up | Runs the AI agent over an emailed deal ā reads replies, decides send/wait/complete, and re-arms the next follow-up. |
Sends one AI-written opener to a READY_TO_EMAIL lead from your mailbox pool, then parks the deal at EMAILED. |
Discover ā qualify ā gate ā find email ā email. An LLM turns your campaign into an ICP filter (cached on the Campaign); discovery pages matching profiles into embedded Leads. Qualification runs the GP + LLM loop over the stored firmographic text. The GP confidence gate promotes QUALIFIED ā READY_TO_FIND_EMAIL, rationing the paid lookup so only the best-fit leads cost a credit. A hit sends an opener; a miss ends the deal as FAILED with a blank outcome (so the ML labeler skips it ā an unfindable address is not a fit signal).
The qualification loop in detail:
Discovered profiles are embedded (384-dim FastEmbed vectors) from the licensed firmographic payload. The backfill chain decides which profile to evaluate next using a balance-driven strategy:
- When negatives outnumber positives ā exploit: pick the profile with highest predicted qualification probability (fill the pipeline with likely positives)
- Otherwise ā explore: pick the profile with highest BALD (Bayesian Active Learning by Disagreement) score (seek the most informative label)
All qualification decisions go through the LLM. The GP model selects which candidate to evaluate next and gates promotion from QUALIFIED to READY_TO_FIND_EMAIL. Every LLM decision feeds back into the model, making candidate selection progressively smarter.
Cold start: With fewer than 2 labelled profiles, the model can't fit ā candidates are selected in order and qualified via LLM. As labels accumulate, the GP gets better at selecting high-value candidates. When the unlabelled pool empties, discovery pages a fresh batch.
Configure behavior via Django Admin (SiteConfig + Campaign).
š Project Structure
āāā docs/ # architecture, configuration, docker, templating, testing
āāā openoutreach/ # single source package; Django apps nested inside
ā āāā settings.py # Django settings (SQLite at data/db.sqlite3)
ā āāā core/ # engine app: daemon, task queue + scheduler,
ā ā # Campaign/SiteConfig/Task, LLM factory, onboarding,
ā ā # ML + discovery/qualify pipeline, the two agents
ā āāā emails/ # discovery/enrichment client, Mailbox + SMTP/IMAP,
ā ā # sender, the four task handlers
ā āāā crm/ # Lead + Deal models
ā āāā chat/ # ChatMessage (per-Deal conversation)
ā āāā legacy/ # model-less migration-history anchor (retired channel)
āāā manage.py # Django management (no args defaults to rundaemon)
āāā local.yml # Docker Compose
āāā Makefile # Shortcuts (setup, run, admin, test)
š Documentation
š¬ Channel
Join for support and discussions: Telegram Channel
šļø Book a Free 15-Minute Call
Got a specific use case, feature request, or questions about setup?
Book a free 15-minute call ā I'd love to hear your needs and improve the tool based on real feedback.
ā¤ļø Support OpenOutreach
This project is built in spare time to provide powerful, free open-source growth tools. Your sponsorship funds faster updates and keeps it free for everyone.
| Tier | Monthly | Benefits |
|---|---|---|
| ā Supporter | $5 | Huge thanks + name in README supporters list |
| š Booster | $25 | All above + priority feature requests + early access to new campaigns |
| š¦ø Hero | $100 | All above + personal 1-on-1 support + influence roadmap |
| š Legend | $500+ | All above + custom feature development + shoutout in releases |
āļø License
GNU GPLv3 ā see LICENCE.md
š Legal Notice
By using this software you accept the Legal Notice. It covers the third-party services you connect (data provider, email-finder, mailbox), your responsibilities as data controller and sender under data-protection and anti-spam law, the optional freemium promotional campaign, automatic newsletter subscription for non-opt-in jurisdictions, the central contacts store, and liability disclaimers.
Use at your own risk ā no liability assumed.
Made with ā¤ļø