🎯 ColdLead Studio

Scrape once. Re-score forever. Scientific B2B lead scouting for VibeCoding studios — find the local businesses that most need (and can afford) a 24-hour micro-app, rank them with a transparent 8-variable model, and walk away with a ready-to-send outreach kit.

CLI · MCP server · Agent skill · Local dashboard — one engine, four surfaces.

English · Italiano

Why

Classic scrapers hand you a flat list of names and phone numbers. You still don't know who has money, who is reachable, who is toxic, and what to pitch them. ColdLead Studio answers exactly that, with numbers you can inspect:

• 🧮 Precision Opportunity Score (POS, 0–100) from 8 normalized variables, context multipliers and hard red-flag filters — every point explained.

• ⚡ Decoupled scoring. Slow work (discovery, website audits, AI insights) runs once and is cached. Re-ranking with new weights is pure math: ~1 ms for a session, from any surface.

• 🎛️ Tamper with the weights post-scraping — sliders in the dashboard, flags in the CLI, arguments in MCP — or pick a preset.

• 🚀 Action Kit per lead: 90-second Loom script, surgical cold email, WhatsApp opener (< 300 chars) and a VibeCoding prompt to build the prototype in Cursor / Claude Code / Antigravity.

• 🆓 Zero-cost by default. Works fully offline with realistic demo data, or live and free with OpenStreetMap. API keys only upgrade things.

Related MCP server: Arara MCP

Quick start

# with uv (recommended) — or: pipx install "coldlead-studio[all] @ git+https://github.com/Gabbo-bruh/coldlead-studio"
uv tool install "coldlead-studio[all] @ git+https://github.com/Gabbo-bruh/coldlead-studio"

coldlead scout "Charter nautico" "Portofino" --source demo   # 30 seconds, no keys, no network
coldlead rescore -p high_ticket_luxury                       # instant re-rank from the cache
coldlead explain 1                                           # why is #1 on top?
coldlead kit 1                                               # outreach kit for #1
coldlead web                                                 # interactive dashboard

Drop --source demo to scout real businesses (Google Places if you have a key, otherwise OpenStreetMap — free), with a live technical audit of every website.

git clone https://github.com/Gabbo-bruh/coldlead-studio && cd coldlead-studio
uv sync --all-extras          # or: pip install -e ".[all]"
uv run coldlead --help
uv run pytest                 # 161 tests, fully offline

The model

$$\mathrm{POS} = \left[\frac{\sum_i w_i \cdot V_i}{\sum_i w_i} \times 10\right] \times M_{ads} \times M_{friction} \times T_{win};(\times P_{lock\text{-}in})$$

Multipliers — running ads ×1.25 (they pay for traffic that doesn't convert) · critical friction (no HTTPS / not mobile) ×1.15 · seasonal window ×1.4 autumn-winter, ×1.0 spring, ×0.5 summer peak (--season auto picks it from today's date) · agency lock-in ×0.85.

Red flags discard a lead immediately: owners who insult reviewers or threaten lawsuits, and businesses in liquidation or closed. Tiers: 🔥 Hot ≥ 85 · ⚡ Warm ≥ 65 · 🧊 Low.

Scores are capped at 100 but ranking uses the uncapped value, so ties at the ceiling stay ordered. Every variable ships with human-readable reasons — see coldlead explain or the 🕸 Radar button.

Read the full specification in docs/scoring.md.

Four surfaces, one engine

flowchart LR
    subgraph P1 [Phase 1 · collect once]
        D[Discovery<br/>Google · OSM · demo · CSV import] --> A[Website audit<br/>stack · speed · booking · ads · agency]
        A --> E[Insights<br/>heuristics or LLM]
        E --> C[(Session cache<br/>raw signals JSON)]
    end
    subgraph P2 [Phase 2 · score forever, ~1 ms]
        C --> S[Pure POS engine]
        W[Presets · weights · season] --> S
        S --> O[CLI · Dashboard · MCP · CSV/JSON/MD]
    end

1. CLI — coldlead

Every command is pipe-friendly: -f json/-f csv writes clean data to stdout, messages go to stderr.

2. MCP server

Tools: coldlead_search, coldlead_rescore, coldlead_explain, coldlead_generate_pitch, coldlead_audit, coldlead_score, coldlead_list, coldlead_open_dashboard.

claude mcp add coldlead -- coldlead mcp            # Claude Code

// Claude Desktop · Cursor · Windsurf · Antigravity (mcpServers block)
{ "mcpServers": { "coldlead": { "command": "coldlead", "args": ["mcp"] } } }

Then just ask: "Find 10 boat charters in Portofino, re-rank them favouring automation, and write the WhatsApp opener for the best one." Remote agents can use coldlead mcp --transport streamable-http.

3. Agent skill & Claude Code plugin

The coldlead-scout skill teaches an agent the workflow and the model. It lives in skills/ (synced to .claude/skills/ and .agents/skills/ for Claude Code and Antigravity). The repo is also a Claude Code plugin marketplace:

/plugin marketplace add Gabbo-bruh/coldlead-studio
/plugin install coldlead-studio@coldlead-studio

4. Local dashboard — coldlead web

A "thermal instrument" UI: every lead is a tick on a cold→hot scale; drag any of the 8 weight sliders and the ranking reorders live. Radar chart per lead (lead profile vs. your weights), Action Kit modal with IT/EN copy and one-click export. 📍 Pin on map: drop a pin, pick a radius (0.5–25 km) and scout exactly that area. No build step, no CDN required (the map tiles come from OpenStreetMap), light & dark.

Data sources & keys (all optional)

Copy .env.example to .env. coldlead doctor shows what is active.

Configuration

Four layers, each overriding the previous one: factory presets → ~/.coldlead/config.json → environment (COLDLEAD_PRESET, COLDLEAD_SEASON, COLDLEAD_W_A, …) → runtime (flags, sliders, tool arguments).

// ~/.coldlead/config.json  (create a starter with: coldlead config --init)
{
  "default_preset": "my_luxury_automation",
  "season": "auto",
  "presets": {
    "my_luxury_automation": { "extends": "high_ticket_luxury", "weights": { "w_A": 2.0 } }
  }
}

Factory presets: default_vibe_coding · automation_first · high_ticket_luxury · speedy_cashflow. Weights accept aliases: -w automation=3 equals -w w_A=3.

Output contract

Every surface emits the same POSLeadDossier v1.0.0 record — company, raw_signals, enrichment, pos_evaluation (score, tier, variables, explanations, weights, multipliers, red flags) and optionally action_kit. The JSON Schema is published in schema/pos-lead-dossier.schema.json (coldlead schema).

Use it as a library

from coldlead import demo_leads, resolve_config, score_leads

leads = demo_leads("Dentista", "Milano", limit=8)
for item in score_leads(leads, resolve_config(preset="automation_first", weights={"w_G": 4})):
    print(item.rank, item.evaluation.final_score, item.lead.company.name)

Responsible use

ColdLead Studio audits public homepages with an identifying User-Agent, respects robots.txt by default and keeps request volumes small. You are responsible for complying with the terms of the data sources you enable and with privacy law (in the EU: B2B outreach on legitimate interest, relevant messages, an easy opt-out — the email template includes one). Google Places content may only be stored as the Google Maps Platform terms allow: delete old sessions with coldlead sessions --delete <id>. Demo data is synthetic: names are marked "(demo)", phone numbers are zero-filled and domains use the reserved .example TLD. OpenStreetMap data © OpenStreetMap contributors (ODbL).

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md. The scoring engine is pure and heavily tested, so new variables, presets, playbooks and providers are easy to add.

License

MIT © 2026 Gabriele Crema