By 
Open your laptop on a Monday morning. Three warm leads are already in your inbox — local businesses your AI agent discovered, scored, and personally emailed over the weekend. You didn’t write a single cold pitch. You didn’t spend Sunday night manually searching Google Maps. Your agent did it all, approved nothing without your say-so, and even drafted follow-up messages for anyone who didn’t reply.
This guide walks you through building exactly that — a fully autonomous freelance client acquisition system using Claude Code, Python, and a stack of tools that are either free or very cheap at scale. Whether you’re a web designer, video editor, automation consultant, or any kind of freelancer looking for local clients, this workflow can become your most reliable prospecting tool.
Why You Should Actually Learn This
Most freelancers do client outreach the same way: manually search Google, compile a spreadsheet, write the same cold email twelve times with slight tweaks, send it, wait, repeat. It’s exhausting and it doesn’t scale.
The bottleneck is always the system, not the effort.
Here’s what building this agent gives you:
- Time back. What takes hours of manual prospecting gets compressed into setup, a review session, and a click.
- Consistency. The agent follows up on Day 3, Day 7, and Day 10 automatically. You don’t forget. You don’t get lazy. It just runs.
- Personalization at scale. Every outreach email is uniquely crafted by Claude API based on that specific business’s details — not a copy-paste template.
- A learnable, transferable skill. Once you understand how to build agentic workflows with Claude Code, you can apply the same architecture to dozens of other automation problems.
Tool Cost & Limits at a Glance
⚠️ Pricing Disclaimer: API pricing changes frequently. Every figure below was accurate at the time of writing but should be verified against each provider’s live pricing page before you commit to a plan.
| Tool | Free Tier | Paid Starts At | Key Limit |
|---|---|---|---|
| SerpAPI | 100–250 searches/month | $25/month (1,000 searches) | Resets monthly; no rollover |
| Claude API | ~$5 free credit (new accounts) | Pay-as-you-go | ~$0.003/1K tokens (Sonnet) |
| Google Sheets API | Free | Free | 300 read/write requests per minute |
| Gmail SMTP | Free | Free | 500 emails/day via App Password |
| WhatsApp Cloud API | Free (Meta-hosted) | Free | Opt-in required — see warning below |
| SQLite | Free | Free | No limits for local use |
| Cloudflare Tunnel | Free | Free | Bandwidth limits on free plan |
Realistic monthly cost for a solo freelancer running 2–3 campaigns per week: The free tiers cover you entirely while testing and running small batches. Once you’re running 3–4 campaigns per week targeting 50+ businesses each, expect roughly $25–$30/month — almost all of that being a SerpAPI upgrade plus a few dollars of Claude API usage. Everything else stays free.
Before You Build: What You Need to Know First
You don’t need to be a Python developer to follow this. The entire agent is built using Claude Code — meaning you’re writing prompts in plain English, not code. Claude writes the code for you.
That said, you do need to be comfortable with:
- Following API setup steps (Google Cloud Console, Gmail, SerpAPI — none of these are complicated, just fiddly the first time)
- Managing a
.envfile (this is just a text file where you store your credentials) - Running a Python script from terminal or CMD
If you’ve never done any of that, spend 30 minutes with a YouTube tutorial on “Python virtual environment setup” and “what is a .env file” before coming back. It’ll make the rest of this much smoother.
Where to Learn the Fundamentals (Free)
- Claude Code: Start with the official Anthropic docs at docs.anthropic.com. The Claude Code quickstart is genuinely good.
- SerpAPI: Their documentation at serpapi.com has working Python examples you can copy and test immediately.
- Google Cloud Console: Google’s own “Getting Started with the Sheets API” guide is the clearest walkthrough for service account setup.
- Cloudflare Tunnel: developers.cloudflare.com/cloudflare-one/connections/connect-networks/ — their free tier quickstart is all you need here.
Don’t buy a course for any of this. The official docs are better than 90% of paid tutorials for these specific tools.
The Full Build Roadmap: 18 Steps, Plain English
Here’s the architecture of what you’re building, explained so you actually understand each piece before you write a single prompt.
Phase 1: Gathering Your Credentials
You need four things before writing a single line of code.
Step 1: Get Your SerpAPI Key
Go to serpapi.com, sign up with your Google account. On the dashboard, your API key is right there. Copy it. The free tier gives you 100–250 searches per month — enough to test and run small campaigns, but you’ll want to upgrade for serious volume.
Step 2: Set Up Google Sheets API
This is the most involved setup step, but follow it exactly once and you’ll never need to repeat it. The key concept: you’re creating a Service Account — basically a robot Gmail address that your Python script will use to read and write your Google Sheet. No browser pop-ups, no ongoing OAuth consent — it authenticates silently in the background.
Here’s how:
- Go to console.cloud.google.com and create a new project (name it anything)
- Navigate to APIs & Services → Enable APIs → search for “Google Sheets API” → enable it
- Go to APIs & Services → Service Accounts → Create Service Account
- Give it a name, click Create and Continue, then Done (ignore the permissions dropdown)
- Click the service account you just made → go to the Keys tab → Add Key → JSON → download the file
- Copy the service account’s email address (it looks like
name@project.iam.gserviceaccount.com) - Create a new Google Sheet, name it “LeadHunter,” and share it with that service account email as Editor
Your Python script authenticates using the JSON file and has full access to write data into your Sheet.
Step 3: Get Your Gmail App Password
Search “App Password Gmail” in Google, go to myaccount.google.com, and generate a 16-character app password. This is what lets your agent send emails programmatically through Gmail SMTP without exposing your actual account password.
Step 4: WhatsApp Cloud API Token (Optional — Read the Warning Below)
You can get this through Meta Business Manager. Before you enable it, read this carefully.
⚠️ Legal Warning: Meta’s WhatsApp Business Policy requires explicit opt-in consent before you send any business-initiated message. Sending cold, unsolicited messages to local businesses via WhatsApp violates their Terms of Service and can get your account permanently banned. Stick to email outreach unless the recipient has explicitly opted in to hear from you. The email channel alone is sufficient for this pipeline to work.
Cold email to local businesses is legal in most jurisdictions — including the US under CAN-SPAM and the EU under GDPR’s “legitimate interest” clause for B2B contacts — but you must include your real business name, a valid address, and an unsubscribe option. At the scale this agent operates, those are easy to include in every message.
Phase 2: Setting Up Your Project Environment
Step 5: Create Your Project Folder and .env File
Create a folder called LeadHunter anywhere on your machine. Open it in Claude Code (or VS Code with Claude Code installed). Your first prompt:
Create a .env file for this project with the following variables:
SERP_API_KEY, GOOGLE_SHEET_ID, GOOGLE_SHEET_CREDENTIALS,
SENDER_EMAIL, SENDER_NAME, GMAIL_APP_PASSWORD
Also add the .env file to .gitignore automatically.
Claude will create the file and add it to gitignore so your credentials never accidentally get pushed to GitHub. Fill in each variable with what you collected in Phase 1. The GOOGLE_SHEET_CREDENTIALS value is the full contents of the JSON file you downloaded from the Service Account setup.
Phase 3: Building the Agent in Prompts
You’re going to paste one prompt at a time into Claude Code. Each prompt builds one module of the agent.
Step 6: Project Foundation
Prompt Claude to create the base structure — main.py, config, logging, and an SQLite database. SQLite stores your leads locally so you don’t duplicate work between sessions.
Step 7: SerpAPI Business Discovery Module
This module takes a city + category as input and scrapes matching local businesses from Google Maps data via SerpAPI. Tell Claude to build a deduplication check so the same business doesn’t appear twice across runs.
Step 8: Lead Normalization and Deduplication
Claude builds a scoring rubric into the code here. A business gets points for having a phone number (+20), a website (+20), an address (+20), an email (+15), 10+ reviews (+15), and a rating (+10). Leads without a website score higher in the next step — those are your best prospects if you’re selling web services.
Step 9: Website Checker
This module actively checks whether a scraped business URL resolves to a real, functional website. It distinguishes between: no website at all, a broken/redirect website, and a working website. Especially valuable if you’re selling web design or development services.
Step 10: Lead Scoring and Tier Classification
Using the scores from Step 8 and website status from Step 9, the agent classifies every lead:
- HOT: Score above 70 (no website or broken site, good profile data)
- WARM: Score 45–70
- LOW: Below 45
Only HOT leads get processed for outreach by default.
Step 11: AI Personalization Engine
For each HOT lead, Claude API generates:
- A personalized email referencing that business’s specific name, category, and gap (e.g., “I noticed [Business Name] doesn’t have a website yet”)
- A WhatsApp message variant (only use if you have opt-in consent — see warning above)
- A landing page pitch specific to that business
Step 12: Demo URL Generation
The agent builds a local HTML page for each lead — a mini proposal or demo page — and serves it via Cloudflare Tunnel so you can send the client a live link they can actually open. A concrete demo link in a cold email converts significantly better than a generic pitch.
Step 13: Google Sheets CRM Integration
Every lead gets written to your Google Sheet automatically: Lead ID, Business Name, Category, City, Phone, Website status, Email content, WhatsApp message, Follow-up stage. Your entire pipeline lives in a single shareable Sheet.
Step 14: Human Approval Gate
This is the step most people want to skip in automation — don’t.
The agent surfaces every HOT lead for your approval before sending anything. You see the business name, their details, the email draft, and the demo page. You click Approve or Reject. Only then does the email go out. This keeps you in control and prevents embarrassing mass-sends when the scraped data turns out to be wrong.
Step 15: Email Sending Module
Builds the Gmail SMTP integration with two modes: dry run (test without actually sending) and live mode. Always run dry mode first on your first batch — you’ll catch formatting issues and data problems before anything reaches a real inbox.
Step 16: Error Handling
Handles rate limits, timeouts, and bad data gracefully. Without this, your agent breaks at 2am and you don’t find out until morning.
Step 17: Web Dashboard
Creates a local web UI where you can see your full pipeline, execute steps, and monitor logs in real time. This is what makes the tool actually pleasant to use day-to-day rather than something you dread touching.
Step 18: Follow-Up Engine
The agent monitors every lead it’s emailed and checks for replies. If no reply after Day 3, it sends a follow-up. Day 7, another. Day 10, a final touch. After that, it marks the lead as cold and stops. Most freelancers follow up zero or once — this alone changes your response rate meaningfully.
Common Mistakes That Kill Your Results
Skipping the dry run. Every first-time user wants to go straight to live mode. Don’t. Run dry mode on your first 20 leads to check email quality and data accuracy before anything goes out.
Ignoring the .env security step. If you push your project to GitHub without .gitignore covering your .env, your API keys are public within minutes. Claude Code handles this automatically, but verify it manually before pushing.
Setting max leads too high. The agent has a max lead limit setting. Keep it at 10–15 while you’re learning. At 100 leads, you’ll hit SerpAPI’s free tier cap in one run.
Treating WhatsApp as email. They are not the same legally. Email is generally safe for B2B cold outreach with an opt-out included. WhatsApp requires prior consent. Don’t conflate them.
Expecting perfect data from SerpAPI. Google Maps data has gaps. Some businesses won’t have emails. Some websites will be wrong. The agent handles this gracefully, but don’t expect 100% clean data on every scrape.
Frequently Asked Questions
What’s the real total monthly cost if I run this seriously? Free tiers cover you entirely while testing and running small batches. At productive freelance scale — 3–4 campaigns per week, 50+ businesses each — budget around $25–$30/month, almost entirely from a SerpAPI upgrade. Verify current pricing at serpapi.com before committing since tiers change.
What do I do when Claude’s generated code breaks? It will break sometimes — that’s normal with any code generation workflow. Paste the exact error message back into Claude Code with this prompt: “This error appeared when running the script. Fix it without changing the other modules.” Claude will diagnose and patch it. If a module repeatedly breaks, ask Claude to rewrite just that file from scratch with the same function signature.
Is cold email legal in my country? For B2B outreach, yes in most places — with basic compliance built in. In the US (CAN-SPAM), you can cold email businesses as long as you identify yourself honestly and include an opt-out mechanism. In the EU (GDPR), B2B cold email is permitted under “legitimate interest” when you have a genuine business reason to contact them. Canada (CASL) is stricter and generally requires implied or express consent first. Australia requires prior consent. Whatever jurisdiction you’re in, include your business name, a real reply-to address, and a one-line unsubscribe option in every email — that covers the basics almost everywhere.
Can this work for niches other than local businesses? Yes. The SerpAPI discovery module queries Google Maps and Search by city + category. Swap “restaurant” for “SaaS company” or “e-commerce brand” and the pipeline still runs — though the personalization prompts and scoring weights will need tuning for non-local targets.
What if I don’t know Python at all? You don’t need to write Python — Claude Code writes it for you. You need to be able to run it: install Python 3.11+, run pip install -r requirements.txt, and type python main.py in terminal. If even that feels unfamiliar, spend one afternoon with the official Python “Getting Started” tutorial before attempting this build.
Where to Go From Here
Once you have the basic agent running and have sent your first real batch of approved outreach, here’s how to level it up:
- Swap SerpAPI for Serper.dev — Serper offers 2,500 free trial searches versus SerpAPI’s 100–250/month free tier, making it better for early volume testing before you need to pay.
- Add a reply detection layer — Connect Gmail’s API to actually read incoming replies and auto-update lead status in your Google Sheet.
- Build a vertical-specific version — One agent for restaurants, another for dental clinics. Different scoring weights, different email templates, different demo page designs.
- Sell this as a service — Run this pipeline on behalf of local marketing agencies or other freelancers. You’ve built the system once; running it for a client is just a new
.envfile and a city/category input.
The pattern you’ve learned — discovery, scoring, personalization, human approval, delivery, follow-up — applies well beyond freelance lead gen. Customer support automation, internal ops tools, content pipelines — the same architecture shows up everywhere. Build it once for yourself. Then figure out who else needs it.