Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,26 @@ SUBQ_API_KEY=
# SUBQ_BASE_URL=https://api.subq.ai/v1
# SUBQ_MODEL=subq-preview

# X DMs (optional): your own X developer app at developer.x.com, with OAuth
# 2.0 on (type Web App) and the callback URL Settings shows, e.g.
# http://localhost:4100/api/x/callback on your computer. Then Connect X in
# Settings. The app's X API plan has to include Direct Messages. cold sends
# one approved DM per click, from your own account, never on its own.
X_CLIENT_ID=
X_CLIENT_SECRET=

# Listening (optional): OpenMagpie's watches deliver the posts they match to
# <your COLD>/api/listen/magpie (Settings, Listening shows the URL). Give the
# webhook action the header Authorization: Bearer <this secret>.
COLD_LISTEN_SECRET=

# A push when one of offer's quiz leads qualifies (Settings, Lead alerts):
# the address of an ntfy topic, on ntfy.sh or your own ntfy server. The push
# carries the lead's name and number, so use a long random topic name, or a
# topic that needs COLD_NTFY_TOKEN (an ntfy access token, tk_...).
COLD_NTFY_URL=
COLD_NTFY_TOKEN=

# Hosting (docs/deploy.md). These belong in the server's real environment,
# not in this file, since .env.local lives inside COLD_HOME.
# COLD_PUBLIC_URL=https://cold.example.com
Expand Down
74 changes: 74 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,80 @@

## Unreleased

- **Drive COLD from Claude.** `bun run mcp` is an MCP server over stdio
(`claude mcp add cold -- bun run --cwd /path/to/cold mcp`), with sixteen
tools on COLD's own API, so they keep its rules: status, campaigns and
today's plan for each (who is due with the exact message, who is held,
waiting or skipped and why), prospect lists, recent activity, results, call
scripts and call sheets with the prospect's local time, quiz leads, logging
the dialer's calls and DMs sent by hand, and following or stopping a send.
Sending is two steps: `cold_send_emails` and `cold_send_x_dm` show what
would go out, and send only when called again with `confirm=true` after
you say yes. Every answer reads as Markdown, or as COLD's JSON, in pages
that stay under 25,000 characters. Built on the MCP TypeScript SDK v2.
- **The dialer's calls come back.** Every call the dialer logs with an
outcome becomes a touch in COLD, on the business's or the quiz lead's
timeline: the outcome, the dialer's AI score and tone, and its summary,
once the call has settled. It runs every ten minutes in the background (on
your computer and on Vercel, once across servers), from **Log calls** on
Calls, or with `cold call log`, and a call is never logged twice.
- A call where you talked with them (interested, appointment set, call
back, not interested) pauses their sequences for 90 days, like a reply.
- "Do not call" is an opt-out: nothing goes to them on any channel, and the
dialer's prospect is marked Do Not Contact.
- The decision engine reads the calls in their history. Someone who opted
out is always skipped; "not interested" on a recent call turns reach out
now into later; a wrong or bad number is no longer a way to reach them;
and skipping someone who was interested goes to you to check.
- Quiz leads say how their last call went.
- **Calls at their hour.** A call sheet for a prospect, in the app and from
`cold call sheet`, says what time it is where they are and whether it is
inside calling hours: 8am to 9pm every day unless cold.yaml's new `calls:`
says otherwise (`start`, `end`, `days`). Outside them it says when hours
open ("call from tomorrow 8:00 AM CST"). The time zone comes from a
`timezone` column, else from both their phone's area code (from Google's
libphonenumber, down to the exchange where an area code is split) and
their state or province, and an area that spans zones is called only when
it is inside hours in all of them. A number it can't place is said, never
guessed. Quiz leads it is too early or late to call drop below the ones you
can call now, their Call button waits, and their push says when to call.
- **Quiz leads get called first.** offer's quiz leads (`agencyLeads` in
Twenty) are a prospect source, `twenty:agencyLeads`: the person who took
the quiz (never the business's decision maker, when they came through a
business's own link), their answers and UTM tags as variables, and "Saw
you took our quiz on Nov 2." as the trigger when the business has none.
Calls lists the last two weeks' qualified leads nobody has called yet at
the top, newest first; picking one fills the script in for them, with a
Call button and their answers. With `COLD_NTFY_URL`, a push reaches your
phone through ntfy within a minute of each qualified lead (several at once
come as one), tapping it opens the lead; it looks once a minute across
every server on the database, never pushes a lead twice, retries one that
failed, and never pushes leads from before it was set up. Settings, Lead
alerts sends a test.
- **Picking a dialer prospect fills the script in again.** Prospects from
`twenty:agencyProspects` and `twenty:agencyPeople` were never found by
their key in a call sheet or a research run, so the script kept its
braces.
- **Leads from listening.** OpenMagpie's webhook action delivers the posts
its watches match to `/api/listen/magpie` (with `Authorization: Bearer`
and `COLD_LISTEN_SECRET`). Each match is kept once, however often it is
delivered, and each watch is a prospect source, `listen:<watch>`: the
trigger line is the post itself, quoted, and a post on X carries its
author's handle for an X DM. **Save as a list** in Settings writes a
watch's matches to one of your own lists to fill in and research; saving
again only adds what is new. Prospect sources are defined once, so
research and campaigns accept the same ones.
- **X DMs go out from COLD.** Add your own X developer app in Settings
(`X_CLIENT_ID`, `X_CLIENT_SECRET`) and press **Connect X** for an account:
a campaign's X queue then has **Send on X**, one approved DM per click,
sent from your own account through X's API and logged with X's message
id. A step goes out once, even after two clicks or on two servers. A
follow-up is never sent to someone who has answered since: their reply is
logged instead and the sequence stops for them. **Check X DMs** on the
Inbox logs answers to earlier DMs. X sign-ins are sealed with
`COLD_SECRET_KEY` when it is set, which a hosted server requires.
LinkedIn, Instagram and Facebook stay copy and open.

- **The logs say which database each deployment is on**: at start, a
fingerprint of its address (never the address or the token), the variable
it came from, and when COLD first used it. If the fingerprint changes with
Expand Down
84 changes: 71 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,15 @@ things in one small server:
- **The engine underneath**: pick a sequence, point it at a list, and COLD
works out who is due for which step today. It writes each message with the
prospect's details, sends the emails from your own mailbox, lines up the DMs
for you to send, and prepares your calls. It stops for anyone who replied,
bounced or asked to be left alone, and logs every touch in Twenty.
for you to send (on X, with one click through X's API), and prepares your
calls. It stops for anyone who replied, bounced or asked to be left alone,
and logs every touch in Twenty.

Claude does the research and the first drafts: it finds businesses that fit
your offer, reads their public footprint for one true reason to reach out,
personalizes each message, preps each call and reads each reply. **You approve
everything.** Nothing is sent by AI on its own, DMs are always sent by you, and
calls are always made by you.
everything.** Nothing is sent by AI on its own, DMs are always sent by you
(on X, by your click on Send on X), and calls are always made by you.

Every message comes in two voices: **personal**, sent from your own name and
profiles, and **company**, sent from the brand or a rep. It works with any
Expand All @@ -51,13 +52,29 @@ call scripts and the Do Not Contact list.
- **An app that's yours alone.** `bun run ui` opens it on your computer, or
host it and install it on your phone. Campaigns that show who is due today,
a Send button with live progress you can stop, a DM queue with Copy and Open
buttons, call scripts, the message library, the inbox, analytics, your
buttons (and Send on X), call scripts, the message library, the inbox, analytics, your
waitlist and settings, behind a login only you have. Your mailbox passwords
and API keys stay on your machine or your server.
- **AI that shows its work.** Claude finds prospects and researches them with
web search, and every claim comes with the page it was read on. Drafts,
call prep and reply answers wait for your approval; nothing goes out on its
own.
- **Leads from listening.** Point a watch in
[OpenMagpie](https://github.com/obris-dev/openmagpie) (the self-hostable
listener behind ListeningKit) at COLD's webhook, and every post where
someone asks for what you sell comes in as a prospect whose trigger line is
the post itself, with its link. A post on X can be answered with an X DM;
save a watch as a list to fill in the rest (company, email) and research it.
- **Calls at their hour.** Every call sheet says what time it is for the
prospect, from their phone's area code or their state, and when calling
hours open if they are closed (8am to 9pm by default, `calls:` in
cold.yaml). Areas that span zones are called when every zone is awake.
- **Quiz leads get called first.** Leads from your
[offer](https://github.com/matthewdonsemail-lab/offer) quiz funnel are a
prospect source (`twenty:agencyLeads`) with their answers as variables,
listed at the top of Calls, newest first, until someone calls them. Set
`COLD_NTFY_URL` and a push reaches your phone ([ntfy](https://ntfy.sh)) a
minute after each qualified lead comes in, with their number.
- **The messages are the product.** 45 messages across cold email, LinkedIn,
X, Instagram and Facebook DMs, and call scripts, plus 11 objection answers. Every
channel is covered twice, once as you and once as the company. Each message
Expand All @@ -83,12 +100,19 @@ call scripts and the Do Not Contact list.
and the touch is kept locally, then saved to Twenty before the next run plans
anything.
- **DMs that keep your account.** LinkedIn, X and Instagram restrict accounts
that send DMs from scripts, so `cold` never does. It writes the next DM due,
copies it, opens the profile, and logs what happened when you say. It keeps
a daily cap per platform.
that send DMs from scripts, so `cold` never scripts one. It writes the next
DM due, copies it, opens the profile, and logs what happened when you say.
On X you can connect your account instead (your own X developer app, in
Settings): **Send on X** sends the DM you approved through X's own API,
one per click, checks a follow-up against the conversation first, and
**Check X DMs** logs the answers. It keeps a daily cap per platform.
- **Calls in the dialer.** One command writes the call scripts and objection
answers into the dialer's `agencyScripts`, so they sit next to every live
call. For a handset, `cold call sheet` prints one filled in for a prospect.
Every call the dialer makes comes back into the touch log with its outcome
and the dialer's AI summary: talking with someone pauses their sequences
like a reply, "do not call" is an opt-out on every channel, and the
decision engine reads the calls when it scores them.
- **It tells you what works.** `cold stats` shows the reply rate of every
message and every sequence, so you keep the winners and rewrite the rest.
- **Checked like code.** `bun run check` type-checks, runs the tests (including
Expand Down Expand Up @@ -149,13 +173,13 @@ bun run cold preview founder-direct --source csv:examples/prospects.csv --prospe
| Home | What's been sent, replies and opt-outs this week, and what's due in each campaign. |
| Prospects | Find new prospects with Claude and web search, save them as a list; research a list and save a trigger line per person. |
| Campaigns | A sequence, the account that sends it, an offer and a prospect list (upload a CSV, use an AI list, or use Twenty). |
| Campaign | Due now, waiting, skipped and held back, with reasons. Personalize any due message with AI and approve it. Emails: Send, with live progress. DMs: the queue, plus a checklist download for a VA. |
| Campaign | Due now, waiting, skipped and held back, with reasons. Personalize any due message with AI and approve it. Emails: Send, with live progress. DMs: the queue (on X, Send on X), plus a checklist download for a VA. |
| Sequences | Every message, previewed with real data, editable in place. |
| Calls | Every script and objection answer, filled in for a prospect, and AI call prep. Sync scripts to the dialer. |
| Inbox | Check an inbox for replies, opt-outs and bounces. Claude reads each reply, sorts it (interested, not now, wants out...) and drafts your answer. |
| Inbox | Check an inbox for replies, opt-outs and bounces, and your X DMs for answers. Claude reads each reply, sorts it (interested, not now, wants out...) and drafts your answer. |
| Analytics | Reply rate per sequence and per message. |
| Waitlist | Everyone who joined on your site, with their role and channels. Mark them invited, export a CSV. |
| Settings | Your login and devices, the AI connection, `cold.yaml` (checked before saving), mailbox URLs, the Twenty key, and a test for each. |
| Settings | Your login and devices, the AI connection, `cold.yaml` (checked before saving), mailbox URLs, the Twenty key, Connect X, and a test for each. |

### The site and the waitlist

Expand Down Expand Up @@ -320,6 +344,33 @@ bun run cold email run founder-direct --source csv:examples/prospects.csv --dry-
- Drop `--dry-run` to send. Nothing sends until `cold.yaml` exists and you
confirm the batch.

### From Claude (MCP)

`bun run mcp` serves COLD to Claude, or any MCP client, over stdio: the same
files, database and rules as the app, from your computer. Add it to Claude
Code:

```bash
claude mcp add cold -- bun run --cwd /path/to/cold mcp
```

Or to Claude Desktop, in `claude_desktop_config.json` (give bun's full path,
`~/.bun/bin/bun`, when Desktop can't find it, and `COLD_HOME` when your files
live elsewhere):

```json
{ "mcpServers": { "cold": { "command": "bun", "args": ["run", "--cwd", "/path/to/cold", "mcp"] } } }
```

Then ask in plain words: "what's going out today on the tint campaign?",
"prep me to call Sam", "which quiz leads haven't been called?", "log the
dialer's calls". It reads your status, campaigns and their plan for today,
prospect lists, activity, results, call scripts and sheets (with each
prospect's local time) and quiz leads; logs the dialer's calls and DMs you
sent by hand; and follows or stops a send. Sends wait for you:
`cold_send_emails` and `cold_send_x_dm` only show what would go out, and go
out only when called again with `confirm=true` after you have said yes.

## A day with it

```bash
Expand Down Expand Up @@ -497,7 +548,9 @@ records go to `.cold/touches.jsonl`.
| `cold email verify` | Check addresses with Reacher (`--record` suppresses invalid ones) |
| `cold dm run <sequence>` | Work through today's DMs, or `--export` a checklist for a VA |
| `cold call sync` | Write the call scripts into the dialer |
| `cold call sheet <script>` | Print a call script and every objection answer |
| `cold call sheet <script>` | Print a call script and every objection answer, with the prospect's local time |
| `cold call log` | Log the dialer's calls, with their outcomes, into the touch log (`--dry-run` to check) |
| `bun run mcp` | COLD as an MCP server for Claude, over stdio (see [From Claude](#from-claude-mcp)) |
| `cold stats` | Reply rate per message and per sequence |
| `cold log <prospect>` | Log a touch by hand (a reply on the phone, an opt-out) |

Expand Down Expand Up @@ -573,7 +626,12 @@ src/
outreach/ variables and rendering per prospect
email/ build, send, sync replies, verify
dm/ the DM queue
call/ dialer script sync and call sheets
call/ dialer script sync, call sheets, and the dialer's calls into the touch log
callHours/ each prospect's local time and calling hours (phone prefix zones from libphonenumber)
leads/ offer's quiz leads: the call-first list and the ntfy push
listen/ OpenMagpie's listening matches, kept once each
xApi/ X's official API: OAuth 2.0 sign-in and DMs
mcp/ COLD as an MCP server: the tools, over its own API
stats/ reply rates
twenty/ the API client and the schema
cli/ terminal input and output
Expand Down
Loading
Loading