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.
Add interactive setup wizard for first-time users
Ethand72365d96bf6
diff --git a/README.md b/README.mdindex c420067..4914e69 100644--- a/README.md+++ b/README.md@@ -143,7 +143,51 @@ pip install -r requirements.txtplaywright install chromium```-### 2. Train Harvey on Your Product+### 2. Run Harvey (First-Time Setup Wizard)++Just run Harvey. On the first run, it detects that it's not configured yet and launches an interactive setup wizard that walks you through everything:++```bash+python -m harvey+```++```+╔══════════════════════════════════════════════════════════╗+║ ║+║ Harvey Setup Wizard ║+║ Let's get you closing deals. ║+║ ║+╚══════════════════════════════════════════════════════════╝++ Harvey: Hey. I'm Harvey. Let's get me set up so I can start+ Harvey: closing deals for you. I'll walk you through everything.+ Harvey: This takes about 5 minutes.++──────────────────────────────────────────────────────────+ Step 1/6: Checking Prerequisites+──────────────────────────────────────────────────────────++ Checking Claude Code CLI... ✓ Found+ Testing Claude headless mode... ✓ Working+ Checking Python dependencies... ✓ All installed++──────────────────────────────────────────────────────────+ Step 2/6: Email Platform (Instantly)+──────────────────────────────────────────────────────────+ ...+```++The wizard:+1. **Checks prerequisites** — verifies Claude CLI, tests headless mode, checks dependencies+2. **Connects your email platform** — Instantly API key, tests the connection+3. **Sets up LinkedIn** (optional) — credentials for browser-based prospecting+4. **Configures Cloudflare** (optional) — for deep JS-rendered website crawling+5. **Trains on your product** — crawls your website or walks through manual entry+6. **Sets behavior** — usage limits, quiet hours, send limits, timezone++After setup, Harvey starts its heartbeat loop automatically on future runs. To re-run setup: `python -m harvey.setup`++### Alternative: Train Harvey on Your Product ManuallyPoint Harvey at your website and it learns everything automatically:@@ -334,6 +378,7 @@ harvey/│ ├── brain.py # Claude Code headless wrapper + skills loader│ ├── state.py # SQLite state manager│ ├── config.py # Configuration loader + validation+│ ├── setup.py # Interactive first-run setup wizard│ ├── trainer.py # Auto-train Harvey from a website URL│ ││ ├── agents/diff --git a/harvey/main.py b/harvey/main.pyindex 01694f2..0d8cfd3 100644--- a/harvey/main.py+++ b/harvey/main.py@@ -169,8 +169,43 @@ async def heartbeat():await asyncio.sleep(60)+def _needs_setup() -> bool:+ """Check if Harvey needs first-time setup."""+ from pathlib import Path+ project_root = Path(__file__).parent.parent+ env_file = project_root / ".env"+ config_file = project_root / "harvey.yaml"++ # If .env doesn't exist, definitely needs setup+ if not env_file.exists():+ return True++ # If config still has placeholder values, needs setup+ if config_file.exists():+ try:+ with open(config_file) as f:+ import yaml+ config = yaml.safe_load(f)+ company = config.get("persona", {}).get("company", "")+ if company in ("Your Company", ""):+ return True+ except Exception:+ return True+ else:+ return True++ return False++def main():"""Entry point."""+ # Check for first-time setup+ if _needs_setup():+ print("\n First time running Harvey? Let's get you set up.\n")+ from harvey.setup import run_setup+ asyncio.run(run_setup())+ return+# Graceful shutdown on SIGTERM (for Docker)loop = asyncio.new_event_loop()diff --git a/harvey/setup.py b/harvey/setup.pynew file mode 100644index 0000000..74834ad--- /dev/null+++ b/harvey/setup.py@@ -0,0 +1,517 @@+"""Interactive setup wizard — Claude walks you through everything Harvey needs."""++import asyncio+import logging+import os+import re+import shutil+from pathlib import Path++import yaml+from dotenv import load_dotenv++from harvey.brain import Brain+from harvey.state import StateManager++logger = logging.getLogger("harvey.setup")++PROJECT_ROOT = Path(__file__).parent.parent+ENV_FILE = PROJECT_ROOT / ".env"+ENV_EXAMPLE = PROJECT_ROOT / ".env.example"+CONFIG_FILE = PROJECT_ROOT / "harvey.yaml"+++def _print_harvey(message: str):+ """Print a message as Harvey."""+ print(f"\n Harvey: {message}")+++def _print_step(step: int, total: int, title: str):+ """Print a step header."""+ print(f"\n{'─'*60}")+ print(f" Step {step}/{total}: {title}")+ print(f"{'─'*60}")+++def _ask(prompt: str, default: str = "", required: bool = True, secret: bool = False) -> str:+ """Ask the user a question."""+ suffix = f" [{default}]" if default else ""+ while True:+ try:+ answer = input(f"\n → {prompt}{suffix}: ").strip()+ except (EOFError, KeyboardInterrupt):+ print("\n\n Setup cancelled.")+ raise SystemExit(1)++ if not answer and default:+ return default+ if not answer and required:+ print(" (required — please enter a value)")+ continue+ return answer+++def _ask_yes_no(prompt: str, default: bool = True) -> bool:+ """Ask a yes/no question."""+ suffix = " [Y/n]" if default else " [y/N]"+ try:+ answer = input(f"\n → {prompt}{suffix}: ").strip().lower()+ except (EOFError, KeyboardInterrupt):+ print("\n\n Setup cancelled.")+ raise SystemExit(1)++ if not answer:+ return default+ return answer in ("y", "yes")+++def _check_claude_cli() -> bool:+ """Check if Claude CLI is installed and accessible."""+ return shutil.which("claude") is not None+++async def _test_claude(brain: Brain) -> bool:+ """Test that Claude Code headless mode works."""+ response = await brain.think(+ "Respond with exactly: HARVEY_READY",+ session_id="harvey-setup-test",+ )+ return "HARVEY_READY" in response+++async def _test_instantly(api_key: str) -> bool:+ """Test the Instantly API key."""+ import httpx+ try:+ async with httpx.AsyncClient(timeout=10) as client:+ resp = await client.get(+ "https://api.instantly.ai/api/v2/accounts",+ headers={"Authorization": f"Bearer {api_key}"},+ )+ return resp.status_code == 200+ except Exception:+ return False+++class SetupWizard:+ def __init__(self):+ self.env_vars: dict[str, str] = {}+ self.config: dict = {}++ async def run(self):+ """Run the full interactive setup."""+ print(f"""+╔══════════════════════════════════════════════════════════╗+║ ║+║ Harvey Setup Wizard ║+║ Let's get you closing deals. ║+║ ║+╚══════════════════════════════════════════════════════════╝""")++ _print_harvey("Hey. I'm Harvey. Let's get me set up so I can start")+ _print_harvey("closing deals for you. I'll walk you through everything.")+ _print_harvey("This takes about 5 minutes.\n")++ total_steps = 6++ # Step 1: Check prerequisites+ _print_step(1, total_steps, "Checking Prerequisites")+ await self._check_prerequisites()++ # Step 2: Connect email platform+ _print_step(2, total_steps, "Email Platform (Instantly)")+ await self._setup_email_platform()++ # Step 3: LinkedIn (optional)+ _print_step(3, total_steps, "LinkedIn (Optional)")+ self._setup_linkedin()++ # Step 4: Cloudflare crawling (optional)+ _print_step(4, total_steps, "Website Crawling (Optional)")+ self._setup_cloudflare()++ # Step 5: Train on product+ _print_step(5, total_steps, "Train Harvey on Your Product")+ await self._setup_product()++ # Step 6: Configure behavior+ _print_step(6, total_steps, "Configure Behavior")+ self._setup_behavior()++ # Write everything+ self._write_env()+ self._write_config()++ # Final summary+ await self._print_summary()++ async def _check_prerequisites(self):+ """Verify Claude CLI is installed and working."""+ # Check Claude CLI+ print("\n Checking Claude Code CLI...", end=" ")+ if _check_claude_cli():+ print("✓ Found")+ else:+ print("✗ Not found")+ _print_harvey("I need Claude Code CLI to think. Install it from:")+ print(" https://claude.ai/download")+ print("\n After installing, run 'claude login' to authenticate,")+ print(" then re-run this setup.")+ raise SystemExit(1)++ # Test headless mode+ print(" Testing Claude headless mode...", end=" ", flush=True)+ state = StateManager()+ await state.init_db()+ brain = Brain(state)+ if await _test_claude(brain):+ print("✓ Working")+ else:+ print("✗ Failed")+ _print_harvey("Claude CLI is installed but headless mode isn't working.")+ _print_harvey("Make sure you're logged in: run 'claude login'")+ print("\n Also verify your Max subscription is active.")+ if not _ask_yes_no("Continue anyway?", default=False):+ raise SystemExit(1)++ # Check Python packages+ print(" Checking Python dependencies...", end=" ")+ missing = []+ for pkg in ["httpx", "aiosqlite", "yaml", "pydantic", "bs4"]:+ try:+ __import__(pkg)+ except ImportError:+ missing.append(pkg)+ if not missing:+ print("✓ All installed")+ else:+ print(f"✗ Missing: {', '.join(missing)}")+ print("\n Run: pip install -r requirements.txt")+ if not _ask_yes_no("Continue anyway?", default=False):+ raise SystemExit(1)++ _print_harvey("Prerequisites look good. Let's keep going.")++ async def _setup_email_platform(self):+ """Configure Instantly API."""+ _print_harvey("I need a cold email platform to send campaigns through.")+ _print_harvey("Right now I support Instantly (recommended) and Woodpecker.")++ has_instantly = _ask_yes_no("Do you have an Instantly account?")++ if has_instantly:+ api_key = _ask("Instantly API key (from Settings → Integrations)")+ self.env_vars["INSTANTLY_API_KEY"] = api_key++ # Test the key+ print("\n Testing API key...", end=" ", flush=True)+ if await _test_instantly(api_key):+ print("✓ Connected")+ _print_harvey("Perfect. I can send campaigns through Instantly now.")+ else:+ print("✗ Failed")+ _print_harvey("Couldn't connect. The key might be wrong, or you might")+ _print_harvey("need the Growth plan for API access. I'll save it anyway —")+ _print_harvey("you can fix it later in .env.")+ else:+ _print_harvey("No problem. You'll need one eventually to send emails.")+ _print_harvey("Sign up at https://instantly.ai (Growth plan for API access).")+ _print_harvey("Add your API key to .env later as INSTANTLY_API_KEY.")+ self.env_vars["INSTANTLY_API_KEY"] = ""++ def _setup_linkedin(self):+ """Configure LinkedIn credentials."""+ _print_harvey("I can search LinkedIn to find prospects matching your ICP.")+ _print_harvey("I'll log into your LinkedIn account using a browser and")+ _print_harvey("search like a human would — with random delays and everything.")++ use_linkedin = _ask_yes_no("Set up LinkedIn prospecting?")++ if use_linkedin:+ email = _ask("LinkedIn email/username")+ password = _ask("LinkedIn password")+ self.env_vars["LINKEDIN_EMAIL"] = email+ self.env_vars["LINKEDIN_PASSWORD"] = password++ _print_harvey("Got it. I'll be careful with your account — human-like")+ _print_harvey("behavior, rate limits, the works. No one will know.")+ else:+ _print_harvey("That's fine. I can still find prospects via Google")+ _print_harvey("and company websites. You can add LinkedIn later.")+ self.env_vars["LINKEDIN_EMAIL"] = ""+ self.env_vars["LINKEDIN_PASSWORD"] = ""++ def _setup_cloudflare(self):+ """Configure Cloudflare Browser Rendering for deep crawling."""+ _print_harvey("When I train on a product website, I can crawl it deeply")+ _print_harvey("using Cloudflare's Browser Rendering API. This means I can")+ _print_harvey("handle JavaScript-heavy sites and crawl hundreds of pages.")+ _print_harvey("It's $5/month for ~12,000 pages. Totally optional.")++ use_cloudflare = _ask_yes_no("Set up Cloudflare crawling?", default=False)++ if use_cloudflare:+ account_id = _ask("Cloudflare Account ID")+ api_token = _ask("Cloudflare API Token (needs Browser Rendering - Edit permission)")+ self.env_vars["CLOUDFLARE_ACCOUNT_ID"] = account_id+ self.env_vars["CLOUDFLARE_API_TOKEN"] = api_token+ _print_harvey("Nice. I'll use Cloudflare for deep crawling during training.")+ else:+ _print_harvey("No problem. I'll use my built-in crawler instead. It works")+ _print_harvey("great for most sites — just can't render JavaScript.")+ self.env_vars["CLOUDFLARE_ACCOUNT_ID"] = ""+ self.env_vars["CLOUDFLARE_API_TOKEN"] = ""++ async def _setup_product(self):+ """Train Harvey on the product — either via URL or manual entry."""+ _print_harvey("Now the important part — I need to learn about what you're selling.")+ _print_harvey("I can either crawl your website and figure it out myself,")+ _print_harvey("or you can tell me the basics manually.\n")++ method = _ask(+ "Train from website URL or enter manually? (url/manual)",+ default="url",+ ).lower()++ if method in ("url", "u", "website"):+ url = _ask("Your product's website URL (e.g. https://yourcompany.com)")++ _print_harvey(f"Give me a minute — I'm going to crawl {url}")+ _print_harvey("and learn everything I can about your product.\n")++ from harvey.trainer import Trainer+ trainer = Trainer()+ self.config = await trainer.train(url, str(CONFIG_FILE)) or {}++ if self.config:+ _print_harvey("Training complete! I've got a solid understanding")+ _print_harvey("of your product now. Check harvey.yaml to review")+ _print_harvey("what I learned — tweak anything that looks off.")+ return++ _print_harvey("Hmm, had trouble with that URL. Let's do it manually.")++ # Manual entry+ _print_harvey("I'll ask you a few questions about your product.\n")++ company = _ask("Company name")+ product = _ask("Product/service name")+ description = _ask("One-line description (what does it do, who is it for?)")+ pricing = _ask("Pricing info", default="Contact for pricing")++ print("\n Enter 3-5 key benefits (one per line, empty line to finish):")+ benefits = []+ while True:+ b = _ask(f" Benefit {len(benefits) + 1}", required=False)+ if not b:+ break+ benefits.append(b)++ _print_harvey("Now let's define your ideal customer.\n")++ industries = _ask("Target industries (comma-separated)").split(",")+ industries = [i.strip() for i in industries if i.strip()]++ titles = _ask("Decision-maker titles (comma-separated)").split(",")+ titles = [t.strip() for t in titles if t.strip()]++ company_size = _ask("Target company size", default="10-200 employees")+ geography = _ask("Target geography", default="United States").split(",")+ geography = [g.strip() for g in geography if g.strip()]++ _print_harvey("What persona should I use for outreach?\n")++ persona_name = _ask("My name (what prospects see)", default="Harvey")+ persona_email = _ask("My email address")+ persona_role = _ask("My title/role", default="Business Development")++ self.config = {+ "persona": {+ "name": persona_name,+ "company": company,+ "role": persona_role,+ "email": persona_email,+ "linkedin": "",+ "tone": "professional, consultative, confident",+ },+ "product": {+ "name": product,+ "description": description,+ "pricing": pricing,+ "key_benefits": benefits or ["Benefit 1"],+ "objection_responses": {},+ },+ "icp": {+ "industries": industries or ["Technology"],+ "company_size": company_size,+ "titles": titles or ["VP", "Director"],+ "geography": geography,+ },+ "channels": {+ "email": {+ "enabled": True,+ "provider": "instantly",+ "max_daily_sends": 50,+ },+ "linkedin": {+ "enabled": bool(self.env_vars.get("LINKEDIN_EMAIL")),+ "max_daily_connections": 20,+ "max_daily_messages": 10,+ },+ },+ "usage": {+ "max_daily_claude_percent": 80,+ "heartbeat_interval_minutes": 15,+ "quiet_hours": {+ "start": "22:00",+ "end": "07:00",+ "timezone": "America/New_York",+ },+ },+ }++ _print_harvey("Got it. I have everything I need about your product.")++ def _setup_behavior(self):+ """Configure Harvey's operational behavior."""+ _print_harvey("Last thing — a few settings for how I operate.\n")++ # Usage limit+ print(" I track my own Claude usage so I don't eat your whole daily quota.")+ usage_pct = _ask(+ "Max % of daily Claude usage I can consume",+ default="80",+ )+ try:+ usage_pct = float(usage_pct)+ except ValueError:+ usage_pct = 80.0++ # Heartbeat interval+ print("\n I wake up on a schedule to check for work.")+ interval = _ask(+ "How often should I check for work (minutes)?",+ default="15",+ )+ try:+ interval = int(interval)+ except ValueError:+ interval = 15++ # Quiet hours+ print("\n I won't send emails or do outreach during quiet hours.")+ quiet_start = _ask("Quiet hours start (24h format)", default="22:00")+ quiet_end = _ask("Quiet hours end (24h format)", default="07:00")+ timezone = _ask("Your timezone", default="America/New_York")++ # Daily send limit+ daily_sends = _ask(+ "Max emails to send per day",+ default="50",+ )+ try:+ daily_sends = int(daily_sends)+ except ValueError:+ daily_sends = 50++ # Update config+ if self.config:+ self.config["usage"] = {+ "max_daily_claude_percent": usage_pct,+ "heartbeat_interval_minutes": interval,+ "quiet_hours": {+ "start": quiet_start,+ "end": quiet_end,+ "timezone": timezone,+ },+ }+ if "channels" in self.config and "email" in self.config["channels"]:+ self.config["channels"]["email"]["max_daily_sends"] = daily_sends++ _print_harvey("Perfect. All configured.")++ def _write_env(self):+ """Write the .env file."""+ lines = []+ for key, value in self.env_vars.items():+ lines.append(f"{key}={value}")++ ENV_FILE.write_text("\n".join(lines) + "\n")+ logger.info(f"Wrote {ENV_FILE}")++ def _write_config(self):+ """Write harvey.yaml (only if we have manual config — trainer writes its own)."""+ if self.config and not CONFIG_FILE.exists():+ with open(CONFIG_FILE, "w") as f:+ yaml.dump(self.config, f, default_flow_style=False, sort_keys=False)+ logger.info(f"Wrote {CONFIG_FILE}")+ elif self.config:+ # Config already exists (from trainer), update behavior settings only+ try:+ with open(CONFIG_FILE) as f:+ existing = yaml.safe_load(f) or {}+ existing["usage"] = self.config.get("usage", existing.get("usage", {}))+ if "channels" in self.config:+ existing.setdefault("channels", {})+ if "email" in self.config["channels"]:+ existing["channels"].setdefault("email", {})+ existing["channels"]["email"]["max_daily_sends"] = (+ self.config["channels"]["email"].get("max_daily_sends", 50)+ )+ with open(CONFIG_FILE, "w") as f:+ yaml.dump(existing, f, default_flow_style=False, sort_keys=False)+ except Exception:+ pass++ async def _print_summary(self):+ """Print final summary and next steps."""+ print(f"""+╔══════════════════════════════════════════════════════════╗+║ ║+║ Setup Complete! ║+║ ║+╚══════════════════════════════════════════════════════════╝+""")++ # Show what's configured+ checks = {+ "Claude Code CLI": _check_claude_cli(),+ "Instantly API": bool(self.env_vars.get("INSTANTLY_API_KEY")),+ "LinkedIn": bool(self.env_vars.get("LINKEDIN_EMAIL")),+ "Cloudflare Crawl": bool(self.env_vars.get("CLOUDFLARE_ACCOUNT_ID")),+ "Product trained": CONFIG_FILE.exists(),+ }++ for name, ok in checks.items():+ status = "✓" if ok else "–"+ print(f" {status} {name}")++ print(f"""+ Files created:+ - .env (your credentials)+ - harvey.yaml (your configuration)++ To start Harvey:+ python -m harvey++ To re-train on a different product:+ python -m harvey.trainer https://newproduct.com++ To re-run this setup:+ python -m harvey.setup+""")+ _print_harvey("I'm ready. Run 'python -m harvey' and I'll start closing.")+ _print_harvey("Always be closing.\n")+++async def run_setup():+ wizard = SetupWizard()+ await wizard.run()+++def main():+ asyncio.run(run_setup())+++if __name__ == "__main__":+ main()