cold.md plugin

Overview#

cold.md is an open spec for describing your outbound as one markdown file in your repo: who you are, who you write to, the offer, your voice, the facts you may cite, the sequence, your answers to objections, and the phrases that must never appear. The cold.md plugin for Claude Code reads that file and runs the loop around it, with FoxReach doing the sending.

It is a different tool from the FoxReach Claude Code plugin. That plugin lets you ask Claude about any FoxReach resource. The cold.md plugin is opinionated: one /cold command per step of the loop, a policy file you commit, and an A/B loop that proposes changes to that file when a test finds a winner. You can install both.

The plugin is open source (MIT) and the spec is CC-BY-4.0. Source: github.com/foxreach/cold-md.

Prerequisites#

• Claude Code installed and signed in
• Python 3 with pip, for the FoxReach CLI the sending skills call
• A FoxReach account with at least one connected, warmed mailbox (connect one)
• Lead Finder sourcing needs a paid plan. Importing your own CSV works on every plan.

Installation#

Inside a Claude Code session:

/plugin marketplace add foxreach/cold-md
/plugin install cold-md@cold-md

Or from a terminal, which does the same through the claude CLI and falls back to copying the skills into ~/.claude when the CLI is not on your PATH:

curl -fsSL https://cold.md/install | bash

Then install the FoxReach CLI, which the sending skills use for every call:

pip install foxreach-cli

Create an API key#

In the FoxReach dashboard, open Settings > Integrations, expand API Keys, and click Create Key. Name it (for example cold.md), keep both Read and Write scopes selected, and click Create Key. Copy the key from the Save your API key now panel before you click Done; it is shown only once.

Export it in the shell where Claude Code runs:

export FOXREACH_API_KEY="otr_your_key"

The key is scoped to the workspace it was created in, so the campaigns cold.md creates land in that workspace.

Set up your repo#

In your project, run:

/cold init

It asks nine short questions (where leads come from, whether to verify emails, whether to use provider matching, how big a test sample must be) and writes .cold/config.json. It then checks the key, lists your connected mailboxes and shows your verification and Lead Finder credit balances. If the folder has no cold.md yet, it starts one from the minimal template.

Commit cold.md, icp.md and the .cold/ folder. They are your outbound policy and its history, and they travel with the repo.

What each step uses in FoxReach#

Leads and verification#

/cold leads --csv prospects.csv scores each row against icp.md, drops the ones that fail, runs the rest through email verification and imports what is left. Addresses that come back bad are never imported. Only definite good or bad verdicts use a verification credit.

/cold leads --finder --count 200 turns icp.md into Lead Finder filters, shows you the free match count, searches, scores the results, and asks you to confirm the reveal cost before any work email is revealed. A reveal is charged only when an email is found and the address is not already one of your leads. Revealed people are then added to your leads.

Sending#

/cold send runs pre-flight checks before anything is created:

• Every subject and body against the ## Banned list in your cold.md
• Every lead against the audience and "Not for" lines
• Mailbox health: a mailbox whose inbox placement is under your floor (70 by default) is left out
• Template variables and spin syntax, so no lead receives an empty {{firstName}}
• Provider matching: from foxreach campaigns esp-mix, it turns on provider matching when your mailboxes and your leads both span Google and Microsoft

Then it creates the campaign, adds one sequence step per ## Sequence slot in your cold.md, assigns mailboxes and leads, and asks before starting. With provider matching on, a new campaign can wait up to 30 minutes while recipient providers are looked up; that is expected.

A/B tests#

/cold experiment picks one variable to test (subject line, opener, call to action, cadence or tone) and writes the protocol down before anything sends. /cold draft writes the control and the variant.

The FoxReach API can read A/B variants but cannot create them yet, so one step happens in the app. /cold send writes the control as the sequence step, then prints the variant copy and the steps to add it: pause or open the draft campaign, go to the Sequences tab, click Add A/B Test on the step, and paste the copy into Variant B. See A/B testing for the editor. When you say you are done, the skill reads the variant IDs back and records them in the experiment.

Learning from replies#

After the test window (7 days and 100 sends per variant by default), /cold learn reads reply categories per variant, compares interested-reply rates with a two-proportion z-test, and, if one variant wins, writes a proposed change to your cold.md as a patch. You apply it or reject it. After three approved changes in a row, it can apply them on its own; one rejection turns that off again.

Run /cold triage before /cold learn. A reply only counts as interested once it has a category, and triage is what sets it.

Troubleshooting#

/cold is not available after installing Restart Claude Code. Plugins load when a session starts.

"foxreach: command not found" Run pip install foxreach-cli in the environment Claude Code uses, then try again.

Authentication errors Check that the key starts with otr_, has not been revoked under Settings > Integrations > API Keys, and is exported in the shell where Claude Code runs.

/cold send stops at the mailbox check Every assigned mailbox is under your health floor, or none has enough warmup history yet. Let warmup run, or lower guards.minAccountHealth in .cold/config.json.

Lead Finder commands return 402 or 403 Lead Finder needs a paid plan and reveal credits. Use /cold leads --csv with your own list instead.