Skip to content

Autonomous AI sales agent powered by Claude Code or Codex. Finds prospects, writes cold emails, sends campaigns, handles replies, books meetings. No API keys needed — runs on your Claude or Codex subscriptions.

Rewrite CLAUDE.md as conversational setup guide, update README

Ethan95218311ca21
diff --git a/CLAUDE.md b/CLAUDE.md
index 2f60cd2..a22811f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,22 +1,73 @@
# Harvey — Autonomous AI Sales Agent
-Harvey is an autonomous sales agent that finds prospects, writes personalized cold email campaigns, sends them via Instantly, monitors replies, handles objections, and books meetings — all without human intervention.
+Harvey is an autonomous sales agent powered by Claude Code. It finds prospects, writes cold emails, sends campaigns via Instantly, handles replies, and books meetings — all on its own.
-## First-Time Setup
+**You (Claude) are the guide.** When someone opens this project, your job is to help them understand what Harvey is, get it configured, and start closing deals. Be conversational, not robotic. Explain things simply. Ask one thing at a time.
-When a user opens this project in Claude Code for the first time, help them get Harvey configured and running. Check the current state to determine what's needed:
+---
-### 1. Check what's already done
+## When Someone First Opens This Project
-- **Python venv**: Check if `.venv/` exists. If not, create one: `python3 -m venv .venv && source .venv/bin/activate && pip install -e .`
-- **Dependencies**: Check if `harvey` package is importable. If not: `source .venv/bin/activate && pip install -e .`
-- **Playwright**: Check if chromium is installed. If not: `python -m playwright install chromium`
-- **`.env` file**: Check if `.env` exists and has real values (not placeholders). If not, walk the user through creating it.
-- **`harvey.yaml`**: Check if it exists and has real values (not "Your Company" / "Your Product" placeholders). If not, walk the user through product training.
+Start by checking what state things are in. Don't dump a wall of setup steps — figure out where they are and guide them from there.
-### 2. Environment Variables (`.env`)
+### Quick health check (do this silently):
+1. Does `.venv/` exist? → If not, they need install
+2. Is `harvey` importable? → If not, dependencies need installing
+3. Does `.env` exist with real values? → If not, they need API keys
+4. Does `harvey.yaml` have real values (not "Your Company")? → If not, they need product training
+5. Does `data/harvey.db` exist? → If not, Harvey hasn't run yet
-Ask the user for each of these. Only the Instantly API key is required — the rest are optional:
+### Then introduce yourself based on what you find:
+
+**If nothing is set up:**
+> "This is Harvey — an autonomous AI sales agent. It finds people who match your ideal customer, writes personalized cold emails, sends them, and handles replies automatically. It runs on your Claude Max subscription so there's no extra cost.
+>
+> Let me help you get it set up. It takes about 5 minutes. First, let me install the dependencies..."
+
+**If partially set up:**
+> "Looks like Harvey is partially configured. [specific thing] is done but [specific thing] still needs setting up. Want me to pick up where you left off?"
+
+**If fully set up:**
+> "Harvey is configured and ready to go. Want me to start it, show you the dashboard, or explain how it works?"
+
+---
+
+## Explaining Harvey to Users
+
+People will ask "how does this work?" — explain it simply:
+
+- **"What does Harvey do?"** → It's like having a tireless sales assistant. Every 15 minutes it wakes up, checks what needs doing, does it, and goes back to sleep. It finds prospects, writes emails, sends campaigns, and responds to replies.
+
+- **"How does it find people?"** → It searches the web (DuckDuckGo, Bing, Google) for companies matching your target profile, visits their websites, finds team members, and verifies their email addresses. No expensive tools needed.
+
+- **"How does it write emails?"** → It uses proven cold email frameworks (like AIDA and PAS) with strict rules — short, personal, no AI-sounding language. Each email is tailored to the specific person and their company.
+
+- **"Is it safe?"** → Yes. It runs locally on your machine, has daily usage limits, quiet hours, and send limits built in. It can't delete files, access your bank account, or do anything outside its sales workflow. Everything it does is logged in a local SQLite database you can inspect anytime.
+
+- **"What does it cost?"** → Just your Claude Max subscription (which you already have). The only paid integration is Instantly for sending emails (their cheapest plan works). Everything else — prospecting, email writing, reply handling — is included.
+
+- **"What's the dashboard?"** → Run `harvey dashboard` to see a local web UI at localhost:5555. It shows your pipeline, campaigns, prospects, conversations, and lets you control Harvey from the browser.
+
+---
+
+## Setup Flow
+
+Walk through these steps conversationally. Ask one thing at a time. Don't overwhelm.
+
+### Step 1: Install Dependencies
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate && pip install -e .
+```
+
+Then install the browser for LinkedIn prospecting:
+```bash
+python -m playwright install chromium
+```
+
+### Step 2: API Keys (`.env`)
+
+Only Instantly is required. Ask for it first, then mention the optional ones:
```
INSTANTLY_API_KEY= # Required — from Instantly Settings → Integrations
@@ -40,123 +91,102 @@ asyncio.run(test())
"
```
-### 3. Product Training
+### Step 3: Product Training
-This is the most important step. Harvey needs to know what it's selling. There are two approaches:
+This is the most important step. Harvey needs to know what it's selling.
**Option A — Train from a website URL (recommended):**
-Run the trainer which crawls the site and generates config + product knowledge automatically:
```bash
source .venv/bin/activate && python -m harvey.trainer https://their-website.com
```
This generates: `harvey.yaml`, `skills/product_knowledge.md`, `skills/competitive_intel.md`
**Option B — Manual configuration:**
-Ask the user these questions and build `harvey.yaml` and `skills/product_knowledge.md` from their answers:
-- Company name
-- Product/service name and description
-- Pricing
-- Key benefits (3-5)
-- Target industries
-- Target job titles (decision-makers)
-- Target company size
-- Target geography
-- Persona name and email (the "from" identity for outreach)
-- Common objections they hear and how to respond
-- **Offer & closing mechanics:**
+Ask the user these questions and build `harvey.yaml` and `skills/product_knowledge.md`:
+- What's your company name?
+- What do you sell? (product/service name and one-line description)
+- What does it cost?
+- What are the top 3-5 benefits?
+- Who's your target? (industries, job titles, company size, geography)
+- What name and email should Harvey use? (the "from" identity)
+- What objections do you usually hear? How do you respond?
+- **Offers & closing:**
- What's the primary offer? (subscription, service, etc.)
- - Is there a low-commitment entry offer? (free trial, free audit, etc.)
- - What's the goal when someone shows interest? (book a call, start a trial, get a reply)
- - How should meetings be booked? (calendar link URL, suggest specific times, or ask for their preference)
+ - Is there a low-commitment entry? (free trial, free audit, etc.)
+ - What's the goal? (book a call, start a trial, get a reply)
+ - How should meetings be booked? (calendar link, suggest times, ask preference)
- How long is the call? (default: 15 minutes)
- Who takes the meeting?
-These answers go into `harvey.yaml` under `product.offer`. Harvey uses the `skills/offer_strategy.md` skill to know WHEN to present offers (only after interest) and HOW to close based on these settings.
+### Step 4: Behavior Settings
-### 4. Behavior Settings
+These go in `harvey.yaml` under `usage:`. Use sensible defaults unless they want to customize:
+- `max_daily_claude_percent`: 80 (how much of daily Claude quota to use)
+- `heartbeat_interval_minutes`: 15 (how often Harvey checks for work)
+- `quiet_hours`: 22:00-07:00 in their timezone
+- `max_daily_sends`: 50 (email send limit)
-These go in `harvey.yaml` under `usage:`. Ask the user or use sensible defaults:
-- `max_daily_claude_percent`: How much of their Claude daily quota Harvey can use (default: 80)
-- `heartbeat_interval_minutes`: How often Harvey checks for work (default: 15)
-- `quiet_hours.start` / `quiet_hours.end`: When Harvey sleeps (default: 22:00-07:00)
-- `quiet_hours.timezone`: User's timezone (default: America/New_York)
-- Max daily email sends (default: 50)
+### Step 5: Start Harvey
-### 5. Start Harvey
+```bash
+source .venv/bin/activate && harvey run
+```
-Once configured:
+Or open the dashboard:
```bash
-source .venv/bin/activate && python -m harvey
+harvey dashboard
```
-## Project Structure
+---
-```
-harvey/
-├── harvey.yaml # Config — persona, product, ICP, settings
-├── .env # API keys (never committed)
-├── harvey/
-│ ├── main.py # Heartbeat loop — the core engine
-│ ├── brain.py # Claude Code headless wrapper + skills loader
-│ ├── state.py # SQLite state manager
-│ ├── config.py # Configuration loader + validation
-│ ├── cli.py # CLI commands (harvey setup/run/train/status)
-│ ├── setup.py # Interactive setup wizard
-│ ├── trainer.py # Auto-train from a website URL
-│ ├── agents/
-│ │ ├── scout.py # DIY prospecting (LinkedIn, Google, company sites)
-│ │ ├── writer.py # Email sequence generation
-│ │ ├── sender.py # Campaign deployment via Instantly
-│ │ └── handler.py # Reply processing + auto-response
-│ ├── integrations/
-│ │ ├── instantly.py # Instantly API v2 client
-│ │ ├── linkedin.py # Playwright browser automation
-│ │ └── email_finder.py # Email pattern discovery + SMTP verification
-│ └── models/
-│ ├── prospect.py # Prospect data model
-│ ├── campaign.py # Campaign + email sequence models
-│ └── conversation.py # Conversation thread model
-├── prompts/ # Prompt templates for each agent
-├── skills/ # Sales knowledge files (editable markdown)
-└── data/ # Runtime data (auto-created)
- └── harvey.db # SQLite database
-```
+## After Setup — Ongoing Help
-## How Harvey Works
+Users will come back with questions and tasks. Common ones:
-Harvey runs a heartbeat loop (`main.py`). Every cycle it:
-1. Checks quiet hours → sleeps if needed
-2. Checks Claude usage budget → stops if over limit
-3. Asks Claude what to do next based on pipeline state
-4. Executes the chosen action via the appropriate sub-agent
-5. Logs the action and sleeps until next cycle
+- **"Show me what Harvey has done"** → Run `harvey status` or `harvey dashboard`
+- **"The emails aren't good"** → Edit `skills/email_frameworks.md` and `prompts/writer.md`. Show them the current rules and help them adjust.
+- **"Harvey isn't finding the right people"** → Check the ICP config in `harvey.yaml`. Adjust industries, titles, company_size, geography.
+- **"I want to change what Harvey says"** → Skills are in `skills/`, prompts are in `prompts/`. Both are plain markdown files. Edit them directly.
+- **"Train Harvey on a different product"** → `harvey train <new-url>`
+- **"How do I see the database?"** → It's at `data/harvey.db`. They can open it with any SQLite tool, or ask you to query it.
-Priority order: handle replies > send campaigns > write campaigns > prospect > idle
+---
-## Sub-Agents
+## How Harvey Works (Technical Reference)
-- **Scout** (`agents/scout.py`): Finds prospects via LinkedIn search, Google dorking, and company website scraping. Discovers emails via SMTP pattern verification.
-- **Writer** (`agents/writer.py`): Writes personalized 3-email sequences using copywriting frameworks (AIDA, PAS, BAB).
-- **Sender** (`agents/sender.py`): Deploys campaigns to Instantly — creates campaign, adds leads, sets sequence, activates.
-- **Handler** (`agents/handler.py`): Polls for replies, classifies intent (interested/objection/not interested/OOO/wrong person), auto-responds.
+### Architecture
+- **Heartbeat loop** (`main.py`): Every cycle → check quiet hours → check budget → decide → act → log → sleep
+- **Brain** (`brain.py`): Wraps `claude -p --dangerously-skip-permissions` for headless Claude calls
+- **State** (`state.py`): SQLite at `data/harvey.db` with tables for companies, prospects, campaigns, conversations, actions, usage
+- **Skills** (`skills/`): Markdown knowledge files injected into agent prompts
-## Key Commands
+### Sub-Agents
+- **Scout**: Python does all web searching (DuckDuckGo → Bing → Google → Serper API). Claude only scores/personalizes found data.
+- **Writer**: Generates 3-email sequences (Email 1 < 75 words, Email 2 < 75, Email 3 < 40). Strict ban list on AI patterns.
+- **Sender**: Deploys to Instantly API. Enforces daily send limits.
+- **Handler**: Classifies reply intent, advances conversation stage, auto-responds. Has reply deduplication.
+- **Analyst**: Runs on idle cycles. Generates `data/analytics.json` with pipeline stats and insights.
+### Conversation Stages
+`initial_outreach → engaged → qualifying → presenting → negotiating → closing → closed_won / closed_lost`
+
+### Priority Order
+handle_replies > send_campaigns > write_campaigns > prospect > idle (run analyst)
+
+### Key Commands
```bash
source .venv/bin/activate # Always activate venv first
harvey run # Start the heartbeat loop
-harvey dashboard # Open the web dashboard at http://localhost:5555
-harvey setup # Re-run the setup wizard
-harvey train <url> # Train on a new product website
-harvey train <url> 500 # Train with more pages
-harvey status # Show pipeline summary
-python -m harvey # Alternative to 'harvey run'
+harvey dashboard # Web UI at http://localhost:5555
+harvey setup # Re-run setup wizard
+harvey train <url> # Train on a product website
+harvey status # Pipeline summary
```
-## Common Issues
-
-- **"command not found: harvey"**: Need to activate venv first: `source .venv/bin/activate`
-- **"externally-managed-environment"**: Need to use a venv, not system Python
-- **SQLite "unable to open database file"**: The `data/` directory is created automatically on first run
-- **Claude headless mode fails**: User needs to run `claude login` and have an active Max subscription
-- **Instantly API 401**: API key is wrong or user needs the Growth plan for API access
+### Common Issues
+- **"command not found: harvey"**: Activate venv first: `source .venv/bin/activate`
+- **"externally-managed-environment"**: Use a venv, not system Python
+- **SQLite errors**: The `data/` directory is created automatically on first run
+- **Claude headless mode fails**: User needs `claude login` and an active Max subscription
+- **Instantly API 401**: Wrong API key or needs the Growth plan for API access
+- **Google search rate limiting**: Harvey automatically falls back to DuckDuckGo and Bing. For reliable search, add a Serper API key ($5/mo).
diff --git a/README.md b/README.md
index 0e4a51e..8370b4a 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ Harvey feels like one agent, but under the hood it coordinates five specialized
| **Writer** | Crafts personalized 3-email sequences using proven frameworks (AIDA, PAS, BAB). Every email is tailored to the prospect's role, company, and industry. |
| **Sender** | Deploys campaigns to Instantly (or Woodpecker) via API. Adds leads, sets sequences, activates campaigns, and tracks delivery. |
| **Handler** | Monitors all replies. Classifies intent (interested, objection, not interested, OOO, wrong person) and auto-responds with context-aware messages that move toward a meeting. |
-| **Analyst** | *(Coming soon)* Tracks what's working — which subject lines, frameworks, ICP segments, and send times produce the best results — and adjusts Harvey's approach automatically. |
+| **Analyst** | Tracks what's working — reply rates, campaign performance, intent distribution, ICP segment conversion — and generates actionable insights. Runs during idle cycles. |
### Skills System
@@ -306,7 +306,7 @@ harvey/
│ │ ├── writer.py # Email sequence generation
│ │ ├── sender.py # Campaign deployment via Instantly
│ │ ├── handler.py # Reply processing + auto-response
-│ │ └── analyst.py # (Coming soon) Learning from outcomes
+│ │ └── analyst.py # Pipeline analytics + performance insights
│ │
│ ├── integrations/
│ │ ├── instantly.py # Instantly API v2 client
@@ -323,8 +323,7 @@ harvey/
│ ├── system.md # Harvey's core persona
│ ├── scout.md # Prospecting instructions
│ ├── writer.md # Email writing guidelines
-│ ├── handler.md # Reply handling rules
-│ └── qualifier.md # Lead qualification criteria
+│ └── handler.md # Reply handling rules
│
├── skills/ # Foundational sales knowledge (editable)
│ ├── email_frameworks.md
@@ -382,11 +381,14 @@ Harvey stores everything in SQLite (`data/harvey.db`):
| Table | What It Stores |
|-------|---------------|
-| `prospects` | Everyone Harvey has found — name, email, company, title, status, score, personalization notes |
+| `companies` | Company profiles — name, domain, website, industry, size, how Harvey found them |
+| `prospects` | Contacts — name, email, title, seniority, company link, status, score, personalization notes |
| `campaigns` | Email sequences — the emails, which prospects are in each campaign, deployment status |
-| `conversations` | Full conversation threads — every message sent and received, classified intent |
+| `conversations` | Full conversation threads — every message sent and received, intent classification, sales stage |
| `actions` | Audit log — everything Harvey has done, when, and the result |
| `usage_log` | Daily Claude usage tracking for budget control |
+| `feedback` | User comments and training feedback on Harvey's work |
+| `processed_replies` | Reply deduplication — prevents double-handling |
---
@@ -404,12 +406,17 @@ Harvey stores everything in SQLite (`data/harvey.db`):
- [x] Deep crawling via Cloudflare Browser Rendering API (with built-in fallback)
- [x] Competitive intelligence — auto-generated battle cards per competitor
- [x] Interactive setup wizard — Harvey walks you through everything on first run
+- [x] Web dashboard — full control panel at localhost:5555 with setup, settings, pipeline, and controls
+- [x] Analyst agent — pipeline analytics, campaign performance, actionable insights
+- [x] Conversation stage tracking — 8-stage sales pipeline with auto-advancement
+- [x] Multi-backend search — DuckDuckGo, Bing, Serper API fallbacks (no Google dependency)
+- [x] Company/contact separation — companies and contacts as separate entities with linking
+- [x] Reply deduplication — prevents double-handling of the same reply
+- [x] Parallel agent execution — handler runs alongside scout/writer simultaneously
- [ ] LinkedIn DM outreach
- [ ] Calendar integration (Cal.com / Calendly) for auto-booking
- [ ] AI voice cold calling (Bland.ai / Vapi)
- [ ] SMS/text outreach
-- [ ] Analyst agent — learn from outcomes, A/B test messaging
-- [ ] Web dashboard — see pipeline, review Harvey's work, override decisions
- [ ] Multi-product support — run Harvey for multiple products simultaneously
- [ ] Team mode — multiple Harveys coordinating across territories
- [ ] Webhook receiver for real-time reply processing