Harvey: Autonomous AI Sales Agent

Verified Setup Guide•Author: Lakeer.ai•MIT License•v0.2.1

What Harvey Actually Is

Harvey is an open-source Python sales agent that runs on your own machine in a continuous autonomous loop. It drives the Claude Code CLI in headless mode, meaning every email it drafts and every reply it analyzes is billed directly to your existing Claude Pro or Max subscription.

Zero API keys, zero token bills. It is not an MCP server: Claude acts as the cognitive brain, while Harvey handles prospecting, enrichment, and cold outreach execution itself. Every 15 minutes it wakes, checks its budget, and prioritizes: handle replies → send outbox → write copy → prospect leads → idle analysis.

Stage	What Happens	Cost
Discover	Finds local businesses (OpenStreetMap by default)	$0 default
Profile	Reads each site: ad pixels, booking, agency, open roles	Free, no model call
Scout / Writer	Scores leads vs your ICP, writes 3-email sequence (75 / 75 / 40 words)	Your Claude plan
Sender	Sends with human-like pacing, daily cap, stops on reply	Your mailbox
Handler	Reads replies, classifies intent, advances stage, queues response	Your Claude plan

Requirements

Runtime

Python 3.11+

Check with python3 --version. macOS ships with 3.9, so run brew install python@3.13 first.

Intelligence

Claude Pro / Max

Requires the Claude Code CLI logged in via claude login. A ChatGPT Plus plan with Codex also works on macOS/Linux.

Outbox

Secondary Mailbox

Gmail or Google Workspace recommended (~$7/mo) hosted on a dedicated secondary domain. Microsoft 365 and standard SMTP also work.

Setup & Installation

Terminal (Fastest Wizard)

git clone https://github.com/ethanplusai/harvey.git
cd harvey
claude

After starting Claude, type: "set up Harvey for me".

The repository ships with an interactive CLAUDE.md that turns Claude Code into an autonomous setup wizard: it checks installed packages, prompts for missing credentials, and trains Harvey directly on your product URL.

💡 Pro-Tip: Instruct Claude to explicitly ask for your approval before touching DNS, creating external accounts, or dispatching emails.

Persona, ICP & Configuration

Define who Harvey is and who it sells to in harvey.yaml (or harvey.local.yaml, which takes precedence and is gitignored so private pricing never enters source control):

harvey.yaml (or harvey.local.yaml)

persona:
  name: "Growth Advisor"
  company: "YourCompany"
  role: "Sales Lead"
  email: "advisor@getyourcompany.com"
  tone: "direct, helpful, zero-fluff"

product:
  name: "Growth Engine"
  description: "AI-driven marketing and pipeline infrastructure"
  pricing: "From $2,500/mo"
  key_benefits:
    - "Automated ad attribution"
    - "Guaranteed pipeline tracking"
  objection_responses: ...
  offer:
    goal: book_call
    booking_method: calendar_link

icp:
  industries: ["B2B SaaS", "E-commerce", "DTC", "Marketing Agencies"]
  titles: ["Founder", "CEO", "CMO", "VP Growth"]
  company_size: "10-250"
  geography: "US, UK, CA, IN"
  hiring_signals: ["Head of Growth", "Performance Marketer"]

channels:
  email:
    provider: gmail
    max_daily_sends: 50
    require_approval: true

usage:
  max_daily_claude_percent: 80
  heartbeat_interval_minutes: 15
  quiet_hours: "21:00-08:00"

Customizing Sales Frameworks:

Harvey's copywriting brain resides in plain Markdown files inside skills/ (email_frameworks.md, objection_handling.md, qualification.md). If sequences sound too pushy, simply edit the Markdown prompt template—no agent restart required.

Daily CLI Commands

harvey status

Pipeline summary and stage health

harvey outbox

Review queued emails (or press A / R in dashboard)

harvey usage

Claude quota gauges + per-agent token use

harvey export

Deliverable prospects to CSV (useful even if you never send)

harvey sending pause

Kill switch: stops all outbound sends instantly

harvey gmail auth

One-time Gmail / Google Workspace OAuth login

Safety Checklist (Before First Send)

01
Human Approval Mode ON by Default
Every generated email stays in your queue awaiting explicit review. Only change require_approval: false after you have verified consistent tone and accuracy.
02
Dedicated Secondary Domain
Never send cold outreach from your primary domain. Use a variant (e.g. getacme.com instead of acme.com) with proper SPF, DKIM, and DMARC authentication configured to prevent domain blacklisting.
03
2 to 4 Week Domain Warmup
Start at 10–20 emails/day per inbox, gradually scaling up by ~5 emails daily. The default 50/day limit is an absolute ceiling, not a day-one quota.
04
3% Bounce-Rate Auto Kill Switch
If bounce rates exceed 3%, halt immediately to clean prospect data. Harvey automatically trips its built-in kill switch when error thresholds are crossed.
05
CAN-SPAM Physical Address & Unsubscribes
Include a physical mailing address in the footer of your emails. Harvey handles any recipient opt-out request as permanent and immediate.

Honest Caveats & Diagnostics

Meeting Confirmation

Harvey engages prospects and pushes toward calls via your calendar link or suggested times. Full automated calendar slot booking is still on the roadmap, so you verify and confirm the actual calendar invitation.

Legal & Sender Liability

As the sender, you bear legal compliance responsibilities (CAN-SPAM, GDPR/PECR, CASL). If directly asked by a recipient, Harvey answers truthfully that it is an AI agent.

OpenStreetMap Limitations

Free OpenStreetMap discovery relies on registered commercial premises; mobile trades (roofers, plumbers) are sparse. Use harvey discover --providers for paid sources (~$0.37 / 1,000 leads).

Claude Quota Management

Harvey shares your personal Claude account rate limits. Keep max_daily_claude_percent: 80 so your own daily interactive development work is never starved of tokens.

Troubleshooting Cheat Sheet:

• Test headless mode: claude -p "say hi"

• If "command not found: harvey": run source .venv/bin/activate

• If discovery returns empty list: you skipped harvey signals --confirm free