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:

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

Table of contents

• Why the subscription thing matters
• What Harvey actually does
• Quick start
• You confirm what it looks for
• The prospecting pipeline
• The skills library
• The sub-agents
• Nothing sends without you
• The dashboard
• How the data is stored
• Configuration
• Using a ChatGPT plan instead (Codex)
• Legal and deliverability
• Troubleshooting
• Project structure
• Philosophy
• Roadmap

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:

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 python@3.13 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:

```bash harvey signals # review the catalog harvey signals --confirm free # everything that costs nothing (26 of them) harvey signals --c