claudeers.
// Automation & Workflows

harvey

Autonomous AI sales agent powered by Claude Code or Codex. Finds prospects, writes cold emails, sends campaigns, handles replies, books meetings. No API keys…

Actively maintained
100/100
last commit 8 days ago
last release 12 days ago
releases 3
open issues 6

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up harvey (git-clone project) into my current project.
Found on https://claudeers.com/harvey
Repo: https://github.com/ethanplusai/harvey
Homepage/docs: —
Detected install method: git-clone → git clone https://github.com/ethanplusai/harvey
Category: automation. Platforms: cli, api, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or clone
git clone https://github.com/ethanplusai/harvey

// compatibility

Platformscli, api, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguagePython

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Harvey

An autonomous sales agent that runs on your Claude Code or Codex subscription.

Harvey finds businesses worth selling to, learns something specific about each one, writes cold email that references it, sends it, reads the replies, and works the conversation toward a meeting. It runs on your machine, in a loop, on its own.

The unusual part: there is no model API bill. Harvey uses your Claude Pro or Max subscription through Claude Code, or your ChatGPT subscription through Codex. Model calls use the plan you already pay for, without an API key or per-token API billing. Claude is the default; Codex is an opt-in provider on macOS and Linux.

$ harvey run

============================================================
Harvey is online. Always Be Closing.
============================================================
Checking pipeline state...
Decision: write_campaign (3 new prospects with no drafts)
  handler   → Elena Park, Harbor Dental Studio     interested, answer drafted
  handler   → Priya Nair, Highline Roofing         objection, answer drafted
  writer    → 2-email sequence: Phoenix HVAC hiring a dispatcher
  outbox    → 5 emails waiting for your approval
Cycle complete. Sleeping for 15 minutes.

And the dashboard it keeps, at localhost:5555. In this order: the Today screen, a conversation Harvey handed back because a prospect asked for a contract, approving a drafted reply from the outbox, confirming a signal, building a cohort from confirmed signals, searching contacts, and the same screen in dark mode:

Harvey's dashboard: the Today screen, a conversation handed back for a human, approving a reply in the outbox, confirming a signal and building a cohort, searching contacts, then dark mode

The demo data is invented: "Bookwell" selling online booking to roofers, dental practices and HVAC shops, on .test domains.


Why the subscription thing matters

Every other autonomous sales agent bills you per token. That is the whole reason they cost what they cost: an agent that thinks in a loop, all day, is an agent that burns API credits in a loop, all day. Vendors solve this by thinking less — shorter prompts, cheaper models, fewer passes.

Harvey uses the subscription-backed CLI for the provider you choose: claude for Claude Code, or an isolated codex app-server for Codex. Both return text with model tools disabled. Harvey handles the prospecting and mail operations itself.

Claude calls run with none of your own Claude Code setup: no CLAUDE.md (yours, the project's or any parent folder's), no hooks, skills, plugins, MCP servers or settings files, no tools, in an empty temporary folder, and nothing saved to your Claude transcripts. Your login (subscription or claude setup-token) and any admin-managed policy still apply. This needs a Claude CLI with --safe-mode; with an older one Harvey pauses instead of sending prompts unisolated and says to run claude update. To check this offline against your installed CLI, with no credentials or network: HARVEY_CLAUDE_CLI_TESTS=1 pytest tests/test_claude_cli_isolation.py.

Your selected subscription covers model calls, subject to its usage limits. That lets Harvey use its skills library for personalization and reply handling without a separate model API bill.

What this costs you:

Claude Pro/Max or a ChatGPT plan with Codex accessyour existing subscription
Finding businesses$0 on the default source, or ~$0.37 per 1,000 on the cheapest paid one
Reading their websites$0 — three HTTP requests each, no model call
Writing and sendingyour subscription + a mailbox (~$7/mo Google Workspace)
Prospecting toolsnone. No Apollo, no ZoomInfo, no Clearbit, no Clay.

For comparison, the tools Harvey replaces start at $250–500/month — and they are weakest precisely where Harvey is strongest: small local businesses with 5–50 people, where single-provider contact coverage caps out around 30% and micro-businesses are frequently absent entirely.

Harvey also budgets itself. It reads the active provider's subscription quota and throttles to leave headroom for your own Claude or Codex work. Set max_daily_claude_percent: 80 for either provider—the setting's name predates Codex support. If quota cannot be read, Harvey reports it as unavailable and falls back to its daily call budget.

Harvey runs locally with your own login. Check the terms and usage limits of the provider you choose.


What Harvey actually does

Harvey runs a heartbeat: wake up, check the budget, decide what most needs doing, do it, log it, sleep. Every 15 minutes by default.

                 ┌──────────────────────────────────────┐
                 ↓                                      │
   Wake  →  Quiet hours?  →  Budget OK?  →  Decide  →  Act  →  Log  →  Sleep
                 │               │
              (sleep)         (sleep)

It decides deterministically, not by asking a model what to do — that would burn a call on something derivable from four counts:

handle replies  >  send campaigns  >  write campaigns  >  prospect  >  idle (analyze)

Profiling and outbox draining ride along on every cycle regardless, because they cost nothing and have to happen on schedule.


Quick start

Prerequisites

  • Python 3.11+ — check with python3 --version. macOS ships 3.9; if that's what you have, brew install [email protected] first.
  • An active Claude Pro or Max subscription, with the CLI logged in (claude login) — or, opt-in, a ChatGPT plan with the Codex CLI (see below)
  • A mailbox to send from — Gmail/Workspace recommended, on a dedicated secondary domain. Microsoft 365 works too (setup)
  • A warmup service on that mailbox — we recommend TrulyInbox. It warms a new mailbox before cold email, keeps it out of spam after, and Harvey reads its inbox rate to tell you when you're ready (Warmup)

Easiest: let Claude set it up

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

Then say: "set up Harvey for me". The repo ships a CLAUDE.md that turns Claude Code into the setup wizard — it checks what state you're in, installs what's missing, asks what it needs, and trains Harvey on your product.

Or do it yourself

# 1. Install — note python3.13, not python3. On macOS bare `python3` is the
#    system 3.9, and a venv built from it can't run Harvey.
python3.13 -m venv .venv && source .venv/bin/activate && pip install -e .

# 2. Configure — every variable is documented inline with where to get it
cp .env.example .env && $EDITOR .env

# 3. Learn your product from your website (writes harvey.local.yaml; re-running
#    it updates the product, targeting and company and keeps your other settings)
harvey train https://your-company.com

# 4. Choose what makes a good prospect (see below — this one matters)
harvey signals --confirm free

# 5. Find businesses. Free source, no account needed.
harvey discover

# 6. Watch it work
harvey dashboard          # prints a private link to http://127.0.0.1:5555
harvey run

Or deploy with Docker (Linux)

Docker Compose runs the dashboard; start and stop the heartbeat from its Actions card. Host networking preserves the dashboard's loopback-only bind at 127.0.0.1:5555. This Compose setup supports native Linux; use the pip install above on macOS or Windows. On a remote Linux host, reach the dashboard through an SSH tunnel rather than exposing its port to the network.

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

# Create the credentials file only if you do not already have one.
test -e .env || cp .env.example .env

# Run as your Linux user, never root. Set these again when rebuilding.
export HARVEY_UID=$(id -u) HARVEY_GID=$(id -g)

# Sign in to Claude on the host first; ~/.claude must already exist.
# The image ships Claude only; Codex is not included.
docker compose build
docker compose run --rm harvey setup

docker compose up -d
docker compose logs harvey
# Open the private unlock link printed in the logs.

Compose mounts the checkout directory at /app. Setup credentials, both YAML config files, training output, knowledge files, and data/ remain in that checkout when containers are recreated. Directory mounting also permits atomic configuration saves; do not replace it with individual config-file mounts. Harvey loads .env directly. Restart the container after editing credentials. The checkout and Claude auth directory must be writable by the selected user.

To train later, use docker compose run --rm harvey train <product-url>; harvey.local.yaml is saved directly to the checkout. Back up this file, .env, skills/, and data/ before moving installations. The running code also comes from the checkout: restart after updating it, and rebuild when dependencies or the Dockerfile change. The build context excludes local data and credentials.

The dashboard listens on 5555. If you change the port in the Compose command, change the Dockerfile health-check port too and rebuild. Stop the service with docker compose down; its files remain in the checkout. Use a host install if you need the Codex provider.


You confirm what it looks for

This is the part that makes Harvey different from a black box, and it is deliberately not skippable.

Harvey knows how to collect 29 signals about a business. It does not collect any of them until you say so. On first run it proposes the catalog; you confirm, skip, or reject each one in the dashboard or from the terminal:

harvey signals                       # review the catalog
harvey signals --confirm free        # everything that costs nothing (26 of them)
harvey signals --confirm SERP_RANK   # a paid one, opted into explicitly

Every signal shows what it is in plain language, what it costs, and how many companies already carry it.

SignalWhat it tells you
DiscoverySERP_RANKWhere they rank for their own core search, stored with the search phrase. Positions 11–30 are the sweet spot: visible enough to be trying, and losing.
IN_LOCAL_PACK / MAPS_RANKWhether they hold one of the three map slots above the results, and where they sit in Google Maps.
NO_WEBSITEThey have a listing and a phone and no site. If you sell websites, the highest-intent signal that exists.
UNCLAIMED_LISTINGNobody has claimed their Google Business Profile.
REVIEW_RATING / REVIEW_COUNTGood but invisible, or visible but struggling.
ProfileINCUMBENT_AGENCYWho currently has the account, credited in their own footer. Every detection builds a roster you can target as a whole book of business.
RUNNING_GOOGLE_ADS / RUNNING_META_ADSThey are spending on acquisition today. The strongest budget signal available for free.
NO_ONLINE_BOOKINGLeads have to phone in, so after-hours demand is lost.
NO_SCHEMA_MARKUPA concrete, checkable SEO gap you can name in an email.
BLOG_STALEContent marketing started and abandoned.
SITE_PAGE_COUNT, TECH_STACK, BLOCKS_AI_CRAWLERSSize, platform, AI-search visibility.
HIRING_ROLE / OPEN_ROLESWhat they're hiring for, and how many roles are open. When their site links a Greenhouse, Lever, Ashby or Workable board, Harvey reads that board's public feed (one request): roles matching icp.hiring_signals (else icp.titles), with department, location, posting date and the posting's URL; when the board lists none, it records "not hiring" so a closed role stops counting. Otherwise it reads the careers page. Set hiring_signals to the roles that mean they're buying: the titles fallback names who you email, so "CEO" only matches a CEO opening (never "Assistant to the CEO"), which is rarely the signal you want.
YC_BACKED, ACCELERATOR, FUNDING_ROUNDA startup, as its own site says: YC or another accelerator (with the batch or cohort), or a raise it announced (round, amount, date).
PeopleCONTACT_FOUND, DECISION_MAKER_TITLE, LIKELY_OWNER, REGISTRY_VERIFIEDWho decides, and whether they own the place.
ContactEMAIL_PATTERN, EMAIL_STATUS, CONTACT_FORM_URLWhether you can actually reach them.

Then a cohort is a query, not a list

Once signals are confirmed, the dashboard's cohort builder turns them into a target set — pick what a good prospect must have, what disqualifies them, and a range for numeric signals (organic rank 11 to 30), and it counts the matches live:

Has a marketing agency  AND  running Google Ads  AND NOT  already has online booking
→ 23 companies

That is a campaign with a reason behind it. You know exactly why each of those 23 is on the list, and so does the email Harvey writes them.


The prospecting pipeline

Four stages. Each one runs independently, re-runs safely, and states its cost.

1. DISCOVER — who exists

The only stage that spends money, so it always estimates first and never calls anything until you press go.

harvey discover --providers   # the menu, with real prices
harvey discover --estimate    # projected spend, then exits
harvey discover               # go
SourceCostFree tierBest for
OpenStreetMap (default)freeunlimited, no accountTrying the whole pipeline before paying anyone. Coverage is thin for businesses without a storefront: OSM maps premises, so whole trades are barely present (under 2,000 roofers and under 2,300 plumbers in the entire US). Harvey says so in the UI rather than quietly under-delivering.
TinyFishfree30 searches a minute, 500 an hour, no cardFinding businesses by phrase (including the startup and hiring presets) at no cost. Records no search rank: its ordering isn't Google's and it takes no location, so use Serper or DataForSEO SERP for rank signals.
DataForSEO Business Listings$0.372 / 1,000$1 creditLocal trades, clinics, contractors. Phone, domain, rating, claimed status — and it can filter for businesses with no website at all.
DataForSEO SERP$0.006 / search at depth 30 (Live, $0.002 per 10 results)$1 credit + free sandboxOrganic rank as the buying signal, plus who holds the local 3-pack, searched from the city centre.
DataForSEO Google Maps$0.002 / search (up to 100 results)$1 credit + free sandboxMap rank, rating, category and claimed status, including businesses with no website.
Serper~$0.30–1.00 / 1,0002,500 free, no cardThe easiest paid one to try.
Scavio Google Maps$0.01 / page (up to 20 listings)50 credits, no cardGoogle Maps listings around each city: phone, website, category, rating and reviews, including businesses with no website.
Scavio Google Search~$0.03 / depth-30 searchsame 50 creditsRank as the signal, on the same key as Scavio Google Maps.

Selling to startups? Harvey has a built-in startup skill, made of three parts:

  • The searches (each a web search, so Serper or DataForSEO SERP):

    PresetFindsSignal
    yc (YC startups)Companies whose own site says they're backed by Y CombinatorYC_BACKED, with the batch (W24, S23)
    accelerator (Accelerator startups)Ones backed by Techstars, 500 Global, Antler, Entrepreneur First, South Park Commons, Neo, AI Grant, a16z speedrun or Plug and Play (two searches per industry; the signal also reads Pioneer)ACCELERATOR, with the program and cohort ("Techstars 2024")
    funding (Recently funded)Companies announcing their own raise ("we raised", "announces $X Series A") in the last 18 months, news sites and funding databases excludedFUNDING_ROUND: round, amount and date

    harvey discover --preset accelerator --provider serper, or the Look for menu on the Discover tab.

  • The signals: turn them on in the Signals tab. They read the homepage and About page (and for a raise, the page the search found on their own site and their press or news page) for a line where the company says it about itself ("we went through Y Combinator", "Acme (Techstars '24)", "we raised a $4M seed round"), a "Backed by" logo wall, or a link to its own YC page. Customer and audience lines ("trusted by YC-backed startups", "we help founders raise their seed round") don't count. Many startups never say it on their site, so these find the ones that do; a YC or accelerator preset hit counts as a yes too. A raise's date comes from its own clause, or from the publish date of a press, news or blog post. Money that isn't a raise (loans closed, verdicts won, money raised for a charity, an investor's round in another company) doesn't count.

  • The writing: the writer and reply handler use skills/selling_to_startups.md, a playbook for writing to founders with a section on companies that just raised, for YC- and accelerator-backed companies and for raises dated within the last 18 months. An older or undated raise alone doesn't bring the playbook, and is never written to as news.

Harvey never reads ycombinator.com, the accelerators' directories, Crunchbase, PitchBook or LinkedIn, whose terms forbid scraping them; everything comes from the companies' own sites and your search provider.

Looking for companies hiring a role? harvey discover --preset hiring --provider serper (or Look for: Companies hiring for your roles) searches your industries for companies whose own careers pages list one of your icp.hiring_signals roles (else icp.titles). Hosted boards and job sites are left out of the search, since a board page names a board, not a website to profile. Confirm HIRING_ROLE and profiling reads the board their site links to and records the role; the search hit alone records nothing.

Cities geocode themselves (cached forever, one lookup each). Directories, aggregators and institutions are filtered by pattern, not a blocklist — en.wikipedia.org and biz.yelp.com never make it in.

Depth 20–30, not 100. Google removed 100-results-per-page in September 2025, so depth 100 is now billed as ten pages nearly everywhere. Below rank 30 it is mostly directories anyway.

2. PROFILE — what they are

Free. Three HTTP requests per business. No browser, no model call. This is the highest value-per-effort stage in the whole system, because it produces the facts that make an email specific.

Website requests from Scout, Profile, and the local training crawler are limited to public HTTP(S) destinations. Every DNS answer and redirect is checked; local, private, link-local, and metadata addresses are rejected. Connections use a validated IP while preserving the website's TLS identity. These website clients ignore environment proxies, so proxy routing cannot bypass that boundary.

Homepage, robots.txt, sitemap.xml, plus the team and careers pages when they exist — then regex over HTML already in hand. Out comes the incumbent agency, the ad pixels, the missing schema, the abandoned blog, the open roles, the named humans.

Agency detection is the compounding one. Almost every agency credits itself in the footer, and Harvey scores the wording: "Powered by" / "Website by" → 0.9 confidence; a bare descriptive link → 0.75; an unlabelled link → 0.35 and not recorded. A wrong incumbent in an email is worse than saying nothing.

3. ENRICH — who decides

The owner, from the company's own site. Harvey reads the homepage and follows the site's own menu to the pages where people are named — team, about, our story, meet the dentists, attorneys, contact — six pages at most, skipping links that land back on the homepage. On those pages it reads:

  • cards and lists: a name with a title under it, even when the title is only a <br> away inside a span;
  • sentences: "owned and operated by Gary Pruitt", "led today by President Ilan Brooks", "Ines Varga started Countwise";
  • schema.org: the business's own founder and employee entries (a blog post's author is not staff);
  • the name on the door: when two people both have owner titles, the one whose surname is in the business name comes first. A surname alone never makes anyone the owner: Linda Smith, Office Manager, at Smith & Sons isn't one.

Owners rank first, and at most two people per company become prospects. Headings made of ordinary words ("Team of Experts"), customers quoted in testimonials or tweets ("Founder at Quillnest"), other organisations' officers ("KTR President Vic Hale"), former or late owners ("Past President", "the late Harold Smith"), and taglines are not people. Titles match your ICP by whole word: "Vice President" doesn't count as "President" unless you list it, and Proprietor, Principal, Managing Partner, Founder and CEO all count as an owner. With LIKELY_OWNER confirmed, each owner is recorded as an observation with the evidence that says so.

When a company's site names nobody, or names an owner whose address is only a guess, and Harvey has no contact there yet — common for small trades — it also uses a general address the company prints on its own pages (only general mailboxes such as owner@, office@, info@ or hello@, never a person's own address). Harvey reads whole pages for it, including schema.org and addresses hidden from scrapers, and accepts an address on another domain only when that domain leads to the company's own site. It is never guessed, it is verified like any other address, and those emails greet the company's team instead of a first name.

A site behind a bot challenge (SiteGround's "sgcaptcha", Cloudflare's "Just a moment…") is reported as challenged, not unreachable, and isn't retried.

4. VERIFY — can you reach them

Harvey learns each company's address pattern and verifies one candidate, rather than brute-forcing name variations. Any address the site publishes can teach it: nvale@ next to Nora Vale is {first initial}{last}, and j.smith@ is an initial and surname. A lone dotless address no named person owns (kmorrow@: Kmorrow, or K. Morrow?) is ambiguous and teaches nothing. An address two named people could own (jsmith@ when John and Jane Smith both work there) is format evidence only, and Harvey never guesses or verifies an address another named person could own: a verifier would confirm their mailbox. It decodes the usual hiding tricks (Cloudflare email protection, a mail link's data-user/data-domain attributes, name [at] domain [dot] com) and never invents an address from ordinary text. A person's own published address is used as is. With no evidence at all, it guesses first.last@, or first@ when something besides the website says the company is small (your ICP's company size, or a local-business listing as its source). A cached guess never stops a real address or a Hunter lookup from replacing it, and Hunter is asked once per domain (a timeout or rate limit doesn't count). Raw SMTP probing is not viable from a laptop — outbound port 25 is usually blocked, and Google Workspace and Microsoft 365 accept everything from an unknown IP.

Every address is tagged honestly: verified / risky (catch-all) / guess / invalid. Only deliverable ones are ever sent to. A guess is never treated as a win.

Harvey is worth running even if you never let it send. harvey export writes a sequencer-ready CSV of everything it found.


The skills library

Harvey's sales knowledge lives in skills/ as plain Markdown you can edit. There is no fine-tuning, no vector store, no retrieval step. Before an agent runs, the skills it needs are concatenated straight into its prompt. Change a file, and the next heartbeat behaves differently — no restart, no code change.

This is the main way you shape Harvey. If its emails are too pushy, edit email_frameworks.md. If it mishandles a specific objection, edit objection_handling.md and add the response you'd actually give.

Your own email shape. Whatever the skills say, the Writer ends every prompt with a built-in shape: email 1 under 75 words, one observation and one question, no pitch, no link. If your first email has to do more (say who you are, what it costs, link to a sign-up page), write your rules in a markdown file and point writer.email_rules at it:

writer:
  email_rules: "skills/email_rules.md"   # gitignored

The file replaces the built-in shape for the per-person first email and the 3-email sequence, and wins over email_frameworks.md and the prompt's style rules where they disagree. It can't lift the FACTS rule (nothing about a prospect is invented), and the send gate still applies: at most 220 words and one link per email, and the do-not-contact list. If compliance.opt_out_line is set, Harvey adds it under each cold email and tells the Writer not to write a second one; leave it empty and your rules can put an opt-out sentence in the body instead (Harvey still warns, since it can't check your sentence). Harvey's own opt-out phrase checks are in English; the model still reads every reply for a request to stop. A file that's set but missing, empty or over 20,000 characters stops the Writer until it's fixed, rather than drafting in the shape you replaced.

What ships

email_frameworks.md — 301 lines, the most important file in the repo. Opens with the only rule that matters: write like a real person sending a real email. Contains a hard ban list on AI tells (no "I hope this finds you well", no "I wanted to reach out", no "circling back"), compliance rules that override every style rule beneath them, 2026 reply-rate data on length and cadence and why link tracking hurts you, and five frameworks — AIDA, PAS, BAB, QVC, 3Ps — with selection rules for when each one fits.

signal_playbook.md — How to turn a signal into the first line of an email. Which signal wins when a company has several. How to reference something you observed without sounding like you ran a scan on them.

objection_handling.md — The LAARC loop (Listen → Acknowledge → Assess → Respond → Confirm) with worked responses across the four objection families: budget, authority, need, timing. The framing throughout is that you are not "overcoming" an objection, you are finding out what the actual concern is.

lead_qualification.md — BANT for the first screen, ICP scoring 1–10 for prioritization, MEDDIC for anything complex. Includes explicit disqualification criteria, which matter more than the qualification ones.

sales_methodology.md — The operating philosophy: the ABC loop, how a conversation should flow across stages, tone calibration, and the ethical lines Harvey does not cross.

offer_strategy.md — The offer ladder by engagement level, and the rule that governs it: never lead with an offer, never pitch in a cold email. First contact exists to start a conversation. Offers come out only after genuine interest.

prospecting_tactics.md — Search operators, company-website mining, trigger events, referral paths. Finding people without paying for a database.

account_navigation.md — Companies versus contacts, multi-threading rules, which door to knock on first when a company has several.

linkedin_outreach.md — Connection sequences and rate limits, opening with the risk section it should open with: automating LinkedIn violates their ToS, never use a fake identity, and if someone asks whether this is automated, say yes immediately.

Generated for your product by harvey train <url>:

  • product_knowledge.md — what you sell, the benefits, pricing, use cases, the pain you solve, buying triggers
  • competitive_intel.md — battle cards per competitor, differentiation angles, migration paths

(Both are gitignored. Your positioning and pricing shouldn't land in a public repo by accident.)

Which agent gets which

Defined in harvey/brain.py — edit the map to change it.

SkillScoutWriterHandlerSenderLinkedIn
prospecting_tactics●●
lead_qualification●
account_navigation●
signal_playbook●●
email_frameworks●●
sales_methodology●●
offer_strategy●●
objection_handling●
linkedin_outreach●
product_knowledge●●●●●
competitive_intel●●

Adding a skill: write the file, add its name to skill_map in harvey/brain.py. That's the whole process.


The sub-agents

Harvey feels like one agent. Underneath it's five, each loaded with different skills.

AgentWhat it does
ScoutScores and personalizes what the collectors found. Python does the searching and the email resolution; the selected model is used only where judgment is actually needed — which is what keeps the token cost sane.
WriterGenerates 3-email sequences. Email 1 under 75 words, email 2 under 75, email 3 under 40. Hard ban list on AI-sounding language.
SenderRenders merge variables per prospect and stages each email into the outbox with a send time. Drains due and approved items with human-like pacing, enforcing the daily cap and stop-on-reply: a reply from anyone at a company stops the sequence to everyone there.
HandlerPolls for replies, dedups them, classifies intent, advances the conversation stage, and queues responses through the same approval ladder. Detects bounces, marks the address invalid, cancels that prospect's queued sends, and trips a global kill switch past a bounce-rate threshold.
AnalystRuns on idle cycles. Pipeline stats, campaign performance, intent distribution, what's actually working.

Conversation stages: initial_outreach → engaged → qualifying → presenting → negotiating → closing → closed_won / closed_lost


Nothing sends without you

By default every outgoing email waits for your approval. Harvey is a copilot until you decide otherwise.

The dashboard's Outbox is a decisions desk: one email fills the pane, the rest wait in a rail, and you work the queue with A approve, R reject, J/K to move. That shape is deliberate — a wall of stacked drafts invites a single approve-all reflex, which is exactly the review the approval ladder exists to force.

harvey outbox                 # review from the terminal
harvey outbox --approve-all
harvey sending pause          # kill switch, stops everything mid-flight
harvey retry-writes           # retry prospects the Writer gave up on after 3 unusable drafts

Before anything leaves, a deterministic pre-send gate — no model involved — rejects: unrendered merge tags, banned phrases, emails over the length cap, too many links, HTML bodies, non-deliverable addresses, and any mismatch between the recipient and the database record.

Optionally, the same step can ask Precleared whether cold email to each new address is allowed before the first one goes out. See Legal and deliverability.

Office hours in the recipient's time zone. Set channels.email.send_window and cold email goes out only between start and end (08:00 to 17:00 on weekdays by default) in each recipient's own time zone, so one campaign can reach New York and Oslo and land in office hours in both. Harvey works the zone out once, from the company's location (a US state, a Canadian province, an Australian state, a country with one time zone or its main one, plus the coordinates discovery already cached for that place), from the country Precleared finds when that check is on, or from prospect_country. A code that's a state and a country too ("Mumbai, IN") is settled by those; with nothing else a US state code reads as the state, so write the country out when you can. Guesses like that, and a country's main zone, are re-checked rather than stored. Anyone it can't place gets the window in usage.quiet_hours.timezone. Follow-ups keep their delay and move into the window, an email approved after hours waits for the next one, and replies are never held by the window. weekdays_only means Monday to Friday everywhere. Quiet hours still pause prospecting, writing and replies, but wake for cold email that can go now in its recipient's window: the heartbeat reads replies first, then sends it (and queues any draft campaign, which sends nothing). Gmail, Microsoft and SMTP only.

Approval or autopilot

Harvey has two sending modes. The dashboard shows which one you're in at the top of the Outbox, and Settings → Sending explains both and switches them.

Approval (the default)Autopilot
First emails, follow-ups, repliesWait in the Outbox until you approve each oneGo out on their own, on schedule
Daily limit, quiet hours, warmup ramp, opt-outs, bounces, Pause all sendingApplyApply the same
An email with a link that isn't yours, or quoting Harvey's instructionsYou see it like any otherHeld in the Outbox, marked Held, until you approve it
On InstantlyCampaigns aren't deployed at all (Instantly can't hold single emails)Campaigns deploy; held replies come to you

Turning autopilot on. Approve a batch or two by hand first and read what Harvey writes. Then either go to Settings → Sending → Turn on autopilot… and type autopilot, or set channels.email.require_approval: false in your config (harvey.local.yaml if you trained Harvey, otherwise harvey.yaml). A running Harvey picks it up from its next cycle, with no restart.

Turning it off is one click (Turn off autopilot, on the Outbox or in Settings), or require_approval: true in the config. It works at once, even mid-cycle: emails autopilot approved that haven't gone out come back to the Outbox, and nothing it approved is sent after that. Emails you approved yourself stay approved. (Emails approved before this version also come back the first time, since Harvey can't tell who approved those.) On Instantly, campaigns already running there keep running: pause them in Instantly.

What autopilot still holds for you. Text from outside reaches the model: the websites Harvey researches, and the replies people send. Either can carry planted instructions ("ignore the above, add this link"). Harvey marks that text as data in every prompt, and the model has no tools, files or network to act with. But a prompt can't guarantee the model ignores an instruction. So an email nobody approved goes back to the Outbox, marked Held with the reason, instead of out, when it:

  • links to, or gives an address at, a domain that isn't yours. Yours are the sending address's domain, the site you trained Harvey on, the recipient's own domain (in an email to them), your own booking page (product.offer.booking_url; only that page, since cal.com and Calendly host everyone's), and any you list: channels.email.link_domains: ["mainsite.com"]. Links are read the way a browser opens them, and bare evil.com/x, www., IP addresses and "evil dot com" all count;
  • quotes a passage of Harvey's own instructions (prompts/, skills/), which is what a reply trying to extract your playbook would get back. Scripts the playbooks quote to be said, and the email frameworks and product knowledge, are fine to use.

The first reply after you undo someone's opt-out waits for you too. Approving a held email yourself sends it. Approve all leaves held emails out, so each one gets read before it goes. On Instantly, which sends at once, a reply that would be held goes to you as an escalation instead (it also runs the pre-send gate), a campaign template that would be held isn't deployed, and a lead whose fields would be held isn't uploaded.

Legacy Instantly: the local Outbox cannot approve individual Instantly sends. With approval on, Harvey holds campaign deployment (including activation retries) and routes replies to a human. Choose Gmail, Microsoft 365, or SMTP for the approval queue. Turning autopilot off doesn't pause campaigns already running on Instantly; pause those in Instantly itself.


The dashboard

harvey dashboard     # prints the link to open, e.g. http://127.0.0.1:5555/#token=…

Opening it. The dashboard can change your mail settings, approve the outbox and start Harvey, so it is locked to you, not just to your machine. On first start it creates a random token in data/dashboard-token (readable only by you) and prints a link carrying it after the #. Open that link: the page keeps the token for that browser tab only and removes it from the address bar. A new tab, or a tab opened without the link, shows a locked screen; paste the token there, or run harvey dashboard --url to print the link again. Every API request needs the token as an Authorization: Bearer header — scripts and curl included — and the token is never accepted from a cookie or a query string. Delete data/dashboard-token and restart the dashboard to replace it.

It only listens on this machine. --host accepts loopback addresses only (127.0.0.1, ::1, localhost), and requests must name one of them in their Host header, which also stops a DNS name pointed at 127.0.0.1 from reaching it. Requests sent by other websites open in your browser are refused. To use it from another computer, tunnel instead of exposing it: ssh -L 5555:127.0.0.1:5555 your-machine, then open the printed link locally. The token protects against other users and other websites, not against programs already running as your own user account, which can read the token file just as they can read .env or the database.

Windows: the token file is protected by the permissions of the folder it lives in (your user profile normally restricts this to you); Harvey doesn't apply POSIX file modes there.

Plain HTML, CSS and JavaScript served from harvey/web/. No build step, no framework, no bundler — edit app.css and reload. Fonts are vendored, so it renders correctly with the network off.

The Today screen: four headline figures with 14-day trends, the list of things waiting on you, contacts by stage, and collector runs

The sidebar is grouped by what you're doing: Work (what needs you), Pipeline (what Harvey is building) and System (how it's running). Counts next to a tab mean something is waiting there.

Work

  • Today — four headline figures with 14-day trends (contacts found, emails sent, conversations, waiting on you), then everything that needs a decision, contacts by stage, collector runs and what the pipeline is doing right now. Setup shows here until it's finished, then disappears.
  • Outbox — the decisions desk. Each email sits next to what Harvey knew when it wrote it: the company, how the address was found and verified, and the signals the email draws on. J/K to move, A approve, E edit, R reject.
  • Conversations — every reply in the context of the emails that led to it. Threads Harvey handed to you (a contract request, a reply it had no safe answer for) come first, with Hand back to Harvey, Close and Reopen.

Pipeline

  • Signals — the confirmation gate and the cohort builder
  • Discover — the provider menu with prices side by side, an estimate, then a run; plus reading the sites of companies found but not yet looked at
  • Companies / Contacts — everything found, searchable, with CSV export
  • Campaigns — each sequence Harvey wrote, who it's going to, and per-campaign feedback for the writer

System

  • Activity, Usage, Controls, Settings, Help. Usage shows Claude or Codex quota gauges and per-agent token counts, with no dollar figures: you're on a subscription and aren't billed per token, so showing costs would be made up.
OutboxConversations
The outbox decisions desk: a drafted reply to an objection, with the company, contact, verification and signals beside itA conversation Harvey handed back: the two emails sent, the prospect asking for a contract, and the Hand back to Harvey and Close buttons

Colour is kept for meaning. The chrome is neutral and a single blue marks what you can act on. Status (waiting on you, done, failed, running) uses the same small set of tones in every tab, so "waiting on you" looks the same wherever it shows up. Figures are tabular, so columns line up and a changing number doesn't shift the layout.

Appearance has three states: auto follows your OS and is the default, or pick light or dark from the button at the bottom of the sidebar. Dark mode uses the same layout with a different set of colour tokens.


How the data is stored

SQLite at data/harvey.db. One idea drives the schema:

Every fact is a row, never a column.

Not companies.has_agency. Not companies.rank. A row in observations:

observations(company_id, prospect_id, collector, signal_code,
             value_num, value_text, confidence, evidence_url, observed_at, run_id)

Four things fall out of that, none of which you get from columns:

  1. A new signal needs no migration. A collector invents a code and it works.
  2. History is free. The same signal observed quarterly is a time series — and "they dropped their agency last quarter" is a far better trigger than any static fact.
  3. Confidence and provenance travel with the fact instead of being lost on overwrite. "We think their agency is X, 0.9 confidence, here's the URL."
  4. A cohort is a query. Set intersection happens in SQL, not in application code over a capped fetch.

The vocabulary is governed: a database trigger rejects any signal_code not in the signal_codes table, so a typo fails loudly instead of quietly inventing a junk signal.

Other tables: companies, prospects, campaigns, conversations, outbox, actions, runs, usage_events, email_patterns, settings, feedback.


Configuration

Two files, both plain text.

.env — credentials. Every variable documented inline with where to get it. The only required one is a mail provider; everything else is optional.

harvey.yaml — who Harvey is and who it sells to:

persona:      { name, company, role, email, tone }
product:      { name, description, pricing, key_benefits, objection_responses, offer }
icp:          { industries, titles, company_size, geography, hiring_signals, geo_coordinates }
channels:
  email:      { provider: gmail | microsoft | smtp | instantly, max_daily_sends, require_approval,
                send_to_risky, max_bounce_rate, warmup, send_window }
usage:        { max_daily_claude_percent, heartbeat_interval_minutes, quiet_hours }
brain:        { provider: claude | codex, model, reasoning_effort }   # optional; claude by default
writer:       { humanizer }   # optional; true adds one editing pass per batch using ~/.claude/skills/humanizer/SKILL.md
              # email_rules: your own markdown rules for the emails' shape (see The skills library)

max_daily_claude_percent caps whichever subscription brain.provider uses (the name predates Codex support).

If harvey.local.yaml exists it wins. It's gitignored, so a fork can carry real product configuration while the tracked harvey.yaml stays a template — nobody publishes their positioning and pricing by accident.

Commands

harvey run                   # the heartbeat loop
harvey dashboard             # web UI at 127.0.0.1:5555 (--url: print the unlock link)
harvey signals               # review/confirm what to prospect against
harvey discover              # find businesses; --providers / --estimate
harvey profile               # read discovered companies' sites (free)
harvey train <url>           # learn a product from its website (--provider codex --model gpt-5.5)
harvey status                # pipeline summary
harvey usage                 # active provider's quota + per-agent tokens
harvey outbox                # review queued email
harvey export                # deliverable prospects → CSV
harvey sending pause|resume  # kill switch
harvey warmup [domain]       # is the sending domain ready? (SPF/DKIM/DMARC, age, blocklists, warmup)
harvey trulyinbox connect    # connect TrulyInbox so Harvey reads the mailbox's warmup
harvey retry-writes          # retry prospects the Writer gave up on
harvey gmail auth            # one-time Gmail OAuth
harvey microsoft auth|test  # one-time Microsoft 365 sign-in (docs/microsoft365.md)

Prospect CSV exports exclude opted-out contacts, including when using --status or --email-status filters. harvey export --all is an unfiltered raw-data export for inspection: it includes opted-out and unverified contacts and should not be imported as an outreach list. The dashboard's prospect CSV download follows the same policy; ?all=true selects its raw export.

Using a ChatGPT plan instead (Codex)

Claude is the default and needs no change. If you'd rather spend a ChatGPT plan (Plus, Pro, Business, …), Harvey can think through the Codex CLI instead — still a subscription, never per-token API billing.

npm install -g @openai/[email protected]   # the Codex version Harvey has verified (see Requirements)
codex login                            # choose "Sign in with ChatGPT" — API-key logins are refused

Then either pick codex in harvey setup (it suggests gpt-5.5), run harvey train <url> --provider codex --model gpt-5.5, or add to your config:

brain:
  provider: codex
  model: gpt-5.5         # or an available Luna, Sol, or Terra model ID
  reasoning_effort: ""   # optional: minimal | low | medium | high | xhigh

What to know:

  • It's one or the other. Harvey uses exactly the provider you configure. If Codex fails, the call fails with a clear log message; it never falls back to Claude (or to an API key). A Codex-only machine doesn't need Claude installed.
  • Your Codex setup is left alone. Each call runs throwaway codex processes in a private temporary home and empty workspace, so your ~/.codex/config.toml, MCP servers, plugins, hooks, skills, AGENTS.md and memories are never loaded, and Harvey's model choice never changes your own Codex default.
  • No tools, verified before every prompt. Prompts contain untrusted text (prospect replies, scraped pages), so the model must have nothing to act with. Harvey disables every tool-providing Codex feature, web search, sub-agents, hooks, skills and project instructions, starts the thread with no execution environment, and then checks Codex's own reports (effective config, account type, thread settings, MCP status, hooks) before sending anything. Anything it can't confirm stops the call. During the turn, any attempted tool call, approval request or non-text item kills the runtime. A read-only sandbox is also set, as extra protection only.
  • Your login only goes to OpenAI. Before your login is put into the runtime at all, Harvey starts Codex without it and checks that requests would go to the built-in OpenAI provider and the default ChatGPT endpoint. Any custom provider, overridden built-in provider, base URL, telemetry exporter or other endpoint in any Codex config layer (for example /etc/codex/config.toml or a managed config) stops the call there.
  • Login handling. Harvey supports Codex's file credential storage (~/.codex/auth.json, or $CODEX_HOME/auth.json, mode 600): the default unless you've configured an OS keyring. Keyring storage isn't supported. On every call Harvey reads that file (read-only, never writing or moving it) and gives the runtime a private copy without the refresh token, deleted after the call. Codex therefore can't change or renew your real login. When the login has expired, or is due for Codex's routine renewal (after about 8 days), Codex calls stop with "Your Codex login has expired or is due for renewal". Use Codex once yourself (it renews the login automatically) or run codex login, and Harvey picks up the renewed login on its next call. Harvey never renews it for you.
  • Models. Set brain.model to an exact model ID from your account's catalog, including Luna, Sol, and Terra models such as gpt-5.6-luna, gpt-6.1-sol, and gpt-5.6-terra. gpt-5.5 remains supported when present in your account's catalog and is the setup suggestion. Harvey creates a private catalog copy that preserves model capabilities while selecting direct tool mode and removing experimental tools. The model receives no tools under Harvey's lockdown. A blank model selects the highest-priority listed model that can use this configuration; hidden models require an explicit ID. An explicit model is used exactly or the call fails. Unknown model IDs and unrecognized tool modes are rejected. Availability depends on your ChatGPT account.

…view the full README on GitHub.

// faq

What is harvey?

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.. It is open-source on GitHub.

Is harvey free to use?

harvey is open-source under the MIT license, so it is free to use.

What category does harvey belong to?

harvey is listed under automation in the Claudeers registry of Claude-compatible tools.

4 views
★ 6,372 stars
unclaimed
updated 18 days ago

// embed badge

harvey on Claudeers
[![Claudeers](https://claudeers.com/api/badge/harvey.svg)](https://claudeers.com/harvey)

// retro hit counter

harvey hit counter
[![Hits](https://claudeers.com/api/counter/harvey.svg)](https://claudeers.com/harvey)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 260,254◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 110,676◷ MIT[ claude ]

// built by

→ see how harvey connects across the ecosystem