coldforge

Cold outreach tools want an account, a seat price, and your prospect list on
their servers. coldforge wants a directory. It researches a prospect,
personalizes the opener, schedules a sequenced campaign, and follows up only
with the people who didn't reply — from your terminal, or from any MCP client.

Your leads, your copy and your .env live in one SQLite file you can delete.
Every API key is optional: with none set, the whole pipeline still runs
end-to-end on deterministic fallbacks.

See it run

$ coldforge leads import examples/leads.csv
✓ Imported / updated 3 leads.

$ coldforge campaign create --name q3 --sequence examples/sequence.yml
✓ Created campaign q3 (2 steps).

$ coldforge campaign activate q3 --leads examples/leads.csv
✓ Activated q3: scheduled 6 messages for 3 leads.

$ coldforge campaign preview q3
                                                q3 · active
┌──────────────────┬──────┬──────────────────┬────────────────────────────────────────────────┬───────────┐
│ when             │ step │ to               │ subject                                        │ status    │
├──────────────────┼──────┼──────────────────┼────────────────────────────────────────────────┼───────────┤
│ 2026-07-28 09:00 │ 0    │ [email protected]     │ Acme + manual invoice reconciliation?          │ scheduled │
│ 2026-07-28 09:00 │ 0    │ [email protected] │ Northwind + support tickets piling up          │ scheduled │
│                  │      │                  │ overnight?                                     │           │
│ 2026-07-28 09:00 │ 0    │ [email protected]  │ Vela + flaky CI eating release windows?        │ scheduled │
│ 2026-07-31 09:00 │ 1    │ [email protected]     │ Re: {{original_subject}}                       │ scheduled │
│ 2026-07-31 09:00 │ 1    │ [email protected] │ Re: {{original_subject}}                       │ scheduled │
│ 2026-07-31 09:00 │ 1    │ [email protected]  │ Re: {{original_subject}}                       │ scheduled │
└──────────────────┴──────┴──────────────────┴────────────────────────────────────────────────┴───────────┘

Nothing has left your machine yet. The whole campaign is visible before the
first send, and coldforge tick --dry-run shows exactly what would go out.

The tooling argues with you, too — lint reads the copy the way a spam filter
would and refuses to bless a draft you haven't finished:

$ coldforge lint -l [email protected] -t sales_pain_point
✗ unfilled {{variables}} left in the email
Score: 65/100 — rewrite before sending

Install

git clone https://github.com/Makeph/coldforge && cd coldforge
pip install -e ".[all]"      # or `pip install -e .` for the zero-dependency core
coldforge init

Not on PyPI yet — install from source. (pip install coldforge will be the
one-liner once it's published.)

Python ≥ 3.10. Works on Windows, macOS and Linux. pytest runs the whole
offline suite with no keys and no network.

Guardrails, not throttles

The difference between outreach and spam is mostly restraint, so the restraint
is built into the engine rather than left to your discipline. tick — run it
from cron or Task Scheduler — sends what's due and enforces:

# typical cron line — the worker runs every 15 min during the day
*/15 9-17 * * 1-5  coldforge tick --scan-replies

Two front-ends, one core

            ┌──────────────────────────────────────────────┐
            │  shared core (research · personalize ·        │
            │  templates · sequence · sender · db)          │
            └───────────────┬───────────────┬──────────────┘
                            │               │
                      coldforge CLI     MCP server
                  research→send→follow   research_prospect
                                         draft_email

CLI

coldforge icp build --site acme.io       # read YOUR site → who buys it (editable JSON)
coldforge leads verify                   # syntax / disposable / MX — invalid never sends
coldforge leads score                    # rank every lead 0–100 against the ICP
coldforge templates list                 # browse the pack
coldforge research [email protected]          # store a personalization signal
coldforge draft -l [email protected] -t sales_pain_point --research
coldforge lint -l [email protected] -t sales_pain_point   # spam-filter check the copy
coldforge lint --campaign q3             # …or every message a campaign has scheduled
coldforge doctor acme.io                 # SPF / DKIM / DMARC, 0–100
coldforge reply mark [email protected] --text "pas intéressé"   # auto-classified
coldforge suppress add [email protected]       # do-not-contact list, honoured everywhere
coldforge stage set [email protected] call_booked --note "Thu 14:00"   # the steps after the reply
coldforge funnel q3                      # N contacted → M replied → K calls → won
coldforge stats q3 --by template         # which copy earns replies → double down
coldforge geo check --query "best CRM for real estate agents" --brand acme
coldforge content plan                   # ICP keyword gaps → numbered article briefs

MCP

pip install "coldforge[mcp]"
coldforge mcp        # stdio server

{
  "mcpServers": {
    "coldforge": { "command": "coldforge", "args": ["mcp"] }
  }
}

Twelve tools: research_prospect, draft_email, list_templates,
show_template, check_deliverability, build_icp, score_prospect,
lint_email, classify_reply, geo_check_visibility, plan_content,
draft_article. Ask your assistant "research Alex at Acme and draft a
pain-point cold email" and it drives the same engine the CLI does.

Sequences

A sequence is a list of steps in YAML:

- template: sales_pain_point   # concrete opener from the lead's data + research
  wait_days: 0
  condition: always
- template: followup_bump      # one soft bump, same thread, only if no reply
  wait_days: 3
  condition: no_reply

On activate, every step is pre-scheduled for every lead — which is why the
whole timeline is inspectable before anything sends.

Target the right people

The AutoGTM idea — "drop your site, learn who buys it" — reduced to its
honest core, running on your machine:

coldforge icp build --site acme.io          # scrape your own site → ICP
coldforge leads score                       # every lead scored 0–100 + why
coldforge leads list                        # ranked, best fit first

The ICP is a plain JSON file (~/.coldforge/icp.json) holding the product
summary, the pains it removes, ranked buyer segments, match keywords and an
exclude list of words that cost a lead points — without it, a sheet-metal
shop whose home page says "automation" ranks like a real integrator. The model
proposes, you edit. With ANTHROPIC_API_KEY set an LLM writes the profile
and judges each lead; without it a deterministic keyword heuristic keeps ranking
usable offline.

Visibility on answer engines

BabyLoveGrowth sells "get on Google and ChatGPT's radar" as a black-box
dashboard: it writes articles, builds backlinks, and tracks whether you're
mentioned when someone asks an AI. coldforge takes only the two pieces that port
honestly to a local, keyless-by-default tool — and skips the backlink network,
which can't be faked:

coldforge icp build --site acme.io       # with a key, also derives content_gaps:
                                         #   topics your buyers search for that
                                         #   your own site doesn't visibly answer
coldforge content plan                   # cluster keywords/gaps → article briefs
coldforge content draft 01-...           # write one (LLM if a key is set, else an outline)
coldforge geo check -q "best CRM for real estate agents" -b acme

geo check degrades per engine, independently: set none, one, or all four of
ANTHROPIC_API_KEY / OPENAI_API_KEY / PERPLEXITY_API_KEY / GEMINI_API_KEY;
each configured engine gets asked, the rest are skipped. Pass --lead to save
the result as a research signal — "you don't show up when I ask ChatGPT about
X" is a genuinely concrete cold-email opener.

Reply triage

Replies aren't binary. Each one (IMAP scan or reply mark --text "…") is
classified — interested · not_interested · unsubscribe · ooo · other — in
French and English. Unsubscribes hit the suppression list instantly; stats
shows the category breakdown, and stats --by template tells you which copy
actually earns replies, so you double down and retire the rest.

The funnel

stats stops one step short of the only question a campaign has to answer —
is this worth doing again? — because the steps that matter most happen after
the reply. funnel adds them:

$ coldforge funnel q3
q3
┌─────────────┬────┬─────────────┬───────┐
│ step        │  n │ of previous │       │
├─────────────┼────┼─────────────┼───────┤
│ enrolled    │ 42 │           — │       │
│ contacted   │ 40 │         95% │       │
│ replied     │  7 │         18% │       │
│ interested  │  3 │         43% │       │
│ call_booked │  3 │         43% │ typed │
│ call_done   │  2 │         67% │       │
│ quoted      │  1 │         50% │       │
│ won         │  1 │        100% │       │
└─────────────┴────┴─────────────┴───────┘

Everything up to interested is derived from data the engine already owns, so
it costs no bookkeeping. A booked call can't be detected from an inbox, so the
rest is one command: coldforge stage set <lead> call_booked --note "…". Each
row is a percentage of the row above, which names the problem without a
discussion: 40 contacted → 2 replies is a copy problem, 7 replies → 0 calls is
an offer problem.

Templates

Twelve curated, plaintext, reply-tested templates across sales, sales-fr,
recruiting, partnership, warm-intro, networking, follow-up — each under ~120
words, one CTA, with deliverability notes in the front-matter. The sales-fr
pack is a three-touch French sequence for selling to agencies (opener → soft
bump → breakup, see examples/sequence_fr.yml) with CNIL-style B2B compliance
notes. Add your own by dropping a .md file into ~/.coldforge/templates/.

Configuration

Everything is optional — copy .env.example to .env and fill what you need.

Why this exists

A synthesis of the best ideas from a pile of open-source outreach tools, rebuilt
small and honest:

Responsible use

coldforge is a precision tool, not a spam cannon: low daily caps, send windows,
one-bump follow-ups, an explicit "say no and I'll stop" CTA in the templates,
and a doctor check so you authenticate your domain before sending. Only email
people you have a legitimate reason to contact, honour unsubscribes, and follow
the law that applies to you (CAN-SPAM, GDPR, etc.).

License

MIT © 2026 Makeph