Quickstart

This walkthrough takes you from a fresh install to a draft pitch in your Gmail in about 15 minutes.

Step 1 — Write your ICP

Copy the example and fill in the blanks:

cp cold_pitch_agent/icp_example.yaml my_icp.yaml
$EDITOR my_icp.yaml

The most important fields:

• operator_* — info about you (the person whose name will be on the pitch)
• operator_address — physical mailing address, required by CAN-SPAM
• vertical — the 2–4 industries you focus on
• kind_of_content — what you actually want to write
• root_problem — one sentence describing the problem you solve

If you can’t articulate root_problem yet, write something rough. You’ll refine it after your first 30 pitches.

Step 2 — Build a seed prospect list

Create a JSON file with the prospects you want to pitch. Three is plenty for the first run:

[
  {
    "company": "Acme SaaS",
    "website": "https://acme.example",
    "contact_name": "Sarah Chen",
    "contact_email": "sarah.chen@acme.example",
    "contact_role": "Head of Marketing",
    "linkedin_url": "https://www.linkedin.com/in/sarah-chen-example/",
    "timezone": "America/New_York",
    "industry": "SaaS",
    "maturity": "Series B",
    "content_focus": "long-form blog",
    "temperament_personal": "direct",
    "temperament_process": "founder-led",
    "location": "US",
    "contract_length": "retainer",
    "has_budget_signal": true,
    "root_problem_match": true,
    "revenue_est": 15000000
  }
]

Save it as my_prospects.json.

Step 3 — Dry-run the agent (draft mode)

python -m cold_pitch_agent.agent \
  --icp my_icp.yaml \
  --prospects my_prospects.json \
  --max 3

What happens:

1. The agent opens a Chromium browser and researches each prospect (Google, their site, their blog, LinkedIn).
2. It scores each prospect against your ICP. Skips anyone below 7/10.
3. It checks for a trigger event in the last 90 days. Skips if none found.
4. For prospects that pass, it composes a pitch and lints it. Auto-rewrites up to twice if the linter fails.
5. It saves each pitch as a Gmail draft in your account.
6. It schedules follow-up pitches #2 and #3 (in SQLite — see step 5).
7. It prints a summary of what happened.

This first run will probably take 1–2 minutes per prospect (mostly browser research). Be patient.

Step 4 — Review the drafts

Open mail.google.com → Drafts. You should see a draft for each prospect that passed. Read every one. Cold Pitch Boss is good but not magical; the first pass on a new ICP will have rough edges.

If a draft is wrong:

• Sounds generic? Your ICP root_problem is probably too vague. Tighten it.
• Missing a specific detail? The agent didn’t find what it needed during research. You can paste a specific note from your own research and the agent will use it next time.
• Tone off? Edit the system prompt at cold_pitch_agent/prompts/system_prompt.md.

When a draft is good, click Send. (Or wait until Tuesday 10am their time, which is when the agent scheduled it for.)

Step 5 — See what the agent recorded

Everything goes into a local SQLite database at cold_pitch_agent/data/cold_pitch.db. Open it with the command-line sqlite3 tool or any DB browser:

sqlite3 cold_pitch_agent/data/cold_pitch.db
sqlite> .tables
campaigns           events              prospects
campaign_prospects  pitches

sqlite> SELECT company, icp_match, status FROM prospects;

You can also see the scheduled follow-ups:

SELECT p.pitch_number, pr.company, p.send_at
FROM pitches p JOIN prospects pr ON pr.id = p.prospect_id
WHERE p.sent_at IS NULL
ORDER BY p.send_at;

Step 6 — Switch to send-mode (when you trust the output)

After the first 30–50 drafts feel right, you can let the agent send pitch #1 automatically. Pass --send:

python -m cold_pitch_agent.agent \
  --icp my_icp.yaml \
  --prospects my_prospects.json \
  --max 15 \
  --send

It still drafts pitches #2 and #3 (the follow-ups) for your review. Most people keep follow-ups in draft mode permanently and only auto-send the initial pitch.

That’s it. You’re cold-pitching on autopilot.