diff --git a/.env.example b/.env.example index 150563d..facc6e9 100644 --- a/.env.example +++ b/.env.example @@ -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 +# /api/listen/magpie (Settings, Listening shows the URL). Give the +# webhook action the header Authorization: Bearer . +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 diff --git a/CHANGELOG.md b/CHANGELOG.md index dffac30..8711843 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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:`: 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 diff --git a/README.md b/README.md index 558aad4..c76db53 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -497,7 +548,9 @@ records go to `.cold/touches.jsonl`. | `cold email verify` | Check addresses with Reacher (`--record` suppresses invalid ones) | | `cold dm run ` | 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