How to use your Cold Call CRM

1. Starting it

Everything lives in the folder Desktop > Claude Projects > Cold Calling CRM. Double-click one of these:

• A black Terminal window opens. Leave it open while you work. Closing it stops that program.
• The very first time, it spends a minute installing things. That only happens once (and again after an update).
• If your Mac says the file "can't be opened", right-click it, choose Open, then Open again.
• To scrape, you need both windows open: Start Dashboard and Start Scraper.

2. Real or practice?

• Practice mode has a yellow banner at the top: "Practice mode - made-up businesses". The Call buttons only pretend to ring, nothing reaches a real phone, and everything resets to fresh made-up leads every time you start it. Use it to learn the screens or try out a change.
• The real dashboard has no banner. Its address ends in :8000 (practice ends in :8001).
• The two can be open at the same time. They never share data.

3. The pages

• Leads: every business, with its score (A/B/C) and the reason any were skipped. Upload a CSV here, export, or press Re-score all after changing the scoring rules.
• Dialer: your call list, the call panel and the result picker. Results are always set by you, never automatically.
• Analytics: Dials > Answered > Booked > Showed > Signed, plus best hours, days, trades, numbers and scripts.
• Scripts: your call script, objection answers and text messages. The one marked "in use" shows during calls.
• Sales kit: prices, packages and the quote builder. Prices can be edited on the page.
• Calendar: booked calls and meetings. Tick Showed / Signed here so Analytics adds up.
• Scraper: pick an area and trades, and start a run.
• Settings tab: change your business rules from the browser (see section 5).

4. Backing it up

Do this once a week and before any big change.

• Press Back up at the bottom of the left-hand menu. A file called crm-backup-<date>.db downloads to your Downloads folder. It is the whole database: leads, calls, scripts, bookings, prices.
• Put a copy somewhere safe, like your Google Drive.
• The dashboard also keeps the last 20 of these in data/backups inside the project folder.
• Each time you save on the Settings tab, the old settings are copied to data/backups too (settings-<date>.toml, last 30 kept).
• Once it is online (section 7), the server also backs itself up every night at 3:30am, keeping 30 nights.

Not in the backup: the .env file (your password and Twilio keys). Keep those in your password manager.

5. Where each setting lives

To open .env on your Mac, paste this into Terminal:

open -e ~/Desktop/"Claude Projects/Cold Calling CRM"/.env

(If it says there's no such file, ask Claude to make one from .env.example.) After any change to .env, close the Start Dashboard window and double-click it again.

6. Something went wrong?

There are no Call buttons, or a call won't start

• Calling from the browser needs all six TWILIO_... values in .env. It also needs the dashboard to be online (section 7), because Twilio has to reach it. Until then the Dialer works as a plain list: ring from your own phone and set the result there.
• The message "Calling isn't set up yet. Missing in the .env file: ..." tells you which value is empty.
• When the browser asks to use the microphone, press Allow. If you pressed Block, click the padlock next to the address and allow the microphone.
• "Do Not Call" businesses and leads with no usable number are never dialled. That's on purpose.

Calls ring but don't get through, or nobody answers

• Phone networks flag new numbers that make lots of calls. Register each number as a business line in Twilio (Console > Trust Hub) and don't dial too fast.
• On Analytics, check "Results by phone number". A number with a sudden drop in answers may be flagged as spam, so rest it.
• Make sure your Twilio account has credit (Twilio Console > Billing).
• Ring time on the Settings tab (default 25 seconds) controls how long a phone rings before the call gives up.

The Scraper page says "Scraper offline"

• The Start Scraper window isn't open, or it can't reach the dashboard. Double-click Start Scraper.command and keep both windows open. It goes green within a minute. Waiting runs then start by themselves.
• If the window says "The scraper's Chrome hasn't been signed in yet", run Sign In Scraper Google.command first.

"Google asked the scraper to prove it's human"

• Google noticed the automated searching. The scraper rests for an hour by itself. Leave it for a few hours, then start the run again.
• If it keeps happening, make the scraper slower on the Settings tab (a longer pause between businesses).
• Never sign the scraper into your main Google account.
• If it says Chrome "isn't signed into Google any more", run Sign In Scraper Google.command again with the spare account.

A scrape finds nothing, or nothing qualifies

• Press All checked next to the run. Skipped businesses show their reason ("Not one of your trades", "Too few reviews", "Chain"...).
• Lots of "Not one of your trades"? Add that Google category to your trades on the Settings tab, then press Re-score all on Leads.
• Found = 0 usually means Google is limiting the scraper (see the two problems above), or the area name wasn't recognised. Type it plainly: "Leeds", "North Carolina".
• Businesses already in your dashboard are skipped, so re-scraping the same area finds fewer each time.

Upload says "Couldn't find a column with phone numbers"

• Rename that column's heading to Phone in your spreadsheet and upload again. The business-name column should be called Business or Name.
• In Excel or Numbers, save it as CSV UTF-8 first. The dashboard can't read .xlsx or .numbers files.

Phone numbers look wrong, or a lead has no number

• Numbers are tidied into one standard form: +44... or +1.... A number with no country is read as UK if it starts with 0, and as US if it has 10 digits.
• For a US list, add a Country column saying "USA" so nothing gets mistaken for a UK number.
• Premium numbers (UK 09..., 070..., US 900...) are never dialled. That's on purpose.

Forgot the password

• On your own Mac there is no password.
• Online: change DASHBOARD_PASSWORD in the server's .env file, then restart (Claude can do this for you). Five wrong tries locks you out for 15 minutes.

"Is this practice or real?"

• Look for the yellow banner (practice) and check whether the address ends in :8000 (real) or :8001 (practice). Anything you do in practice disappears at the next start.

Restoring a backup

1. Close the Start Dashboard window, so the dashboard is stopped.
2. Paste this into Terminal. Change the file name to the backup you want. It keeps your current database as crm-before-restore.db first, just in case.
   Copy

   cd ~/Desktop/"Claude Projects/Cold Calling CRM"
   cp data/crm.db data/crm-before-restore.db
   cp ~/Downloads/crm-backup-2026-10-13_120000.db data/crm.db
   rm -f data/crm.db-wal data/crm.db-shm

3. Double-click Start Dashboard.command.

On the server, ask Claude to do this, because it's the same steps with the dashboard service stopped.

7. Putting it online (not done yet)

The plan is to run the dashboard and the scraper on your own Verpex VPS, at a sub-address of your domain, with a padlock (https) and your password. Then calls work from the browser and the scraper runs without your Mac. The VPS is currently down on Verpex's side, so this step is waiting. Everything is ready in the deploy folder. Once the VPS is back, Claude will:

• set up the server (setup-vps.sh). This installs Chrome, the padlock and the nightly backup, and starts the dashboard and scraper automatically, even after a restart;
• help you sign the server's scraper into the spare Google account (signin-scraper.sh);
• send future updates from your Mac (deploy-from-mac.sh). Your data and .env on the server are never overwritten.

Until then, use it on your Mac with the .command files.

Still stuck? Copy the exact message (from the page or the Terminal window) and send it to Claude. Never paste your .env file or passwords.