ClaudeBot GitHub

For macOS and iPhone. Runs on Claude Code.

Claude agents that live on your Mac and text you.

Each bot is one Claude Code session, resumed for every wake-up, with its own workspace and a shared memory of you. It reads your iMessages and mail, keeps your calendar, works on goals for days, and asks on your phone before it sends anything.

macOS 14 · Xcode 16 · iOS 17 · Claude Code · Apple developer account

Recreations of the Mac and iPhone apps with example data. Three bots: Steve runs the mornings, Jesse watches your messages, Chief is hunting for an apartment.

Tue 17 Nov · 07:41 [approval] approved with your owner's edits What the bot hears after you change its draft.

It writes the message. You decide if it goes.

Every send becomes an Approve / Deny card on your Mac, in the phone app, and on the notification itself. Change the wording first if you like. The bot is told what you sent, so the next draft is closer.

Chief
Today 07:38
anything new on the apartment front?👍
Two more. Brooklyn Heights (contact: Rosa) and the Chinatown lease takeover. Both drafts are in your approvals, same style as the Briarwood one you approved.
Wants to send an email
Tolisting-4821@relay.example.com
Subject1BR lease takeover, Chinatown
Hi there! I came across your listing for the 1 bed / 1 bath lease takeover in Chinatown and I am very interested! A bit about me: I am a software engineer, full-time, steady income and good references. It would just be me. I am away until December 14. Would you be open to a video tour before then?
Message Chief
Ask me firstdefault
Every send becomes an Approve / Deny card on your phone and Mac, and on the notification itself.
Allowlist only
Listed recipients go straight out. Everyone else needs approval.
Send freely
No approval.
Never send
Blocked. Set separately for iMessage and email, per bot.
Mon 16 → Fri 20 Nov [mission "Find a 1BR in New York" · work session] Sent by the daemon every few hours, with a fresh brief each time.

Give it a goal. It keeps at it for days.

A mission has a goal, a plan, a log, a deadline and a budget. The bot works on it in sessions on its own rhythm, texts you only for a milestone, a blocker or a decision, and sends one report each evening.

Find a 1BR in New York by Dec 14
Needs youChief
4/7
Chief needs you

Rosa wants a $500 holding deposit by Friday to keep the Brooklyn Heights 1BR off the market until the tour. Should I say yes?

Answer in chat
DeadlineMon 14 Dec · 24d
Budget$6.40 of $20
Next sessionheld for you
Goal

A 1BR under $3,400 in Manhattan or brownstone Brooklyn, move in by Dec 15.

Done when

A lease is signed.

Constraints

No broker fee. Video tours until I'm back on Dec 14.

  1. Check new listings every morning
  2. Keep the "Apartments" tracker up to date
  3. Draft inquiries for anything that fits
  4. Book video tours and add them to the calendar
  5. Compare the shortlist on rent, commute and lease terms
  6. Help with the application for the best one
  7. Read the lease and flag anything unusual
Logcadence 4h · report 18:00
Wrote a 7-step plan. Created the "Apartments" tracker and linked it.
Report22 listings checked, 5 fit. Three inquiries are waiting for your approval.
Two landlords replied. Rosa offers a video tour Thursday at 6pm.
MilestoneTour booked for Thursday 18:00 and added to your calendar.
BlockerChinatown landlord wants proof of income before any tour.
ReportTour went well. Shortlist is down to two. One question for you tomorrow.
Needs youAsked about the $500 holding deposit. Work sessions wait for your answer.
Tue 17 Nov · 13:10 [reply · tracker "Apartments" · row "Brooklyn Heights 1BR" · email #4812 from Rosa] A reply finds its row and wakes the bot that owns it.

Ten threads at once, one table.

When a job runs in parallel, like an apartment hunt, applications or orders, the bot keeps a tracker: one row per thing it is following, with contacts, status and a follow-up date.

A reply from a row's contact lands on that row and wakes its bot, past any filters. No reply by the follow-up date and the bot decides whether to nudge.

Chief
Apartments5 rows · 2 replied · next follow-up in 1d
STATUSRENTVIEWINGNEXT STEPFOLLOW-UPLAST REPLY
Brooklyn Heights 1BRREPLYRosa · email, iMessageTour booked$3,250Thu 19 Nov 18:00Ask about deposit–just now
Chinatown lease takeoverlisting relay · emailReplied$2,980Video, not setSend proof of incomein 1d1d
Briarwood 1BRLeasing office · emailWaiting$2,700–Nudge if no replytoday 14:00–
Astoria 1BR, no feePriya · iMessageDraft to approve$2,850–You approve the inquiry––
UWS alcove studioBrokerPassed$3,600–Over budget, broker fee–2d
Arrives

Mail from moe@example.com, subject "Re: Brooklyn Heights 1BR".

Matches

The sender is a contact on one row. Addresses match exactly, phone numbers on their last 10 digits.

Updates

The row gets its reply time and the pending follow-up is cleared.

Wakes[reply · tracker "Apartments" · row "Brooklyn Heights 1BR" · email #4812 from Rosa]
Wed 18 Nov · 09:30 cbot memory add --kind style --channel email Saved quietly after you rewrote a draft.

One memory of you, shared by every bot.

Facts, people, preferences and writing style live in one place on your Mac and go into every bot's prompt. When you edit a draft before approving it, the pair is kept as an example of how you write, and the bot may save a short rule from it.

Sensitive items wait for you to accept them. Passwords, card numbers and codes are never stored.

Memorywhat your bots know about youAdd
Waiting for youA bot wants to remember something sensitive. Nothing is used until you accept it.
Income for rental applicationsAbout you · from Chief · sensitive
AcceptReject
About you6
Back in New York Dec 14

Out of state until then. Tours by video only.

from you
Works as a software engineer

Full-time. Mention for rental inquiries.

from Chief
People14
Rosa

Landlord, Brooklyn Heights 1BR. Answers texts faster than email.

from Chief
Dana

Friend. Usually on WhatsApp. Saturday dinners.

from Jesse
Preferences9
Apartment budget

Under $3,400. No broker fees.

from you
Morning briefing

Weekdays at 7, three items at most.

from Steve
Writing style4
Email to strangers

Plain and short. No exclamation marks. Use their name. Sign off "Thanks, Sam".

from Chief · learned from your edit
iMessage

Lowercase is fine. No sign-off.

from Jesse
How you writeMessages you approved. Your bots read these to sound like you; your edits teach them most.
you edited thisEmail
THE BOT'S DRAFT

Hi there! I came across your listing for the 1 bed / 1 bath in Brooklyn Heights and I am very interested! A bit about me: I am a software engineer, full-time, good credit…

WHAT YOU SENT

Hi Rosa, I saw your listing for the 1BR on Henry St. I'm a software engineer with steady income and good references. Could we do a video tour this week? Thanks, Sam

Weekdays · 07:00 [scheduled "Morning briefing"] Steve set this schedule himself after you asked once.

It wakes up on its own.

Nothing runs while a bot is idle. It wakes for your texts, on a heartbeat, on schedules it sets for itself, and for incoming messages and mail that get past its filters and a quick triage check.

Up nextTue 17 Nov
SteveMorning briefing · every weekday
ChiefMission work session
ChiefFollow up: Briarwood 1BR
JesseHeartbeat
Heartbeat
Every N minutes while idle.
Daily budget
Past its cap, only you can wake the bot until midnight.
Quiet hours
Texts arrive without a push unless marked urgent.
Steve
Today 07:00
Morning. Three things today:
· Dentist at 10:00 on Atlantic Ave. Leave by 9:35, the F is running slow.
· Rent reminder is due Friday.
· Dana emailed about Saturday's dinner. Want me to draft a yes?
Tuesday 17 November
DentistAtlantic Ave
Lunch with Dana
Video tour: Brooklyn Heights 1BRadded by Chief
Message Steve
Sat 21 Nov · 11:12 [incoming iMessage from Dana] One of the headers a bot sees, so it knows where each message came from.

Your messages, your mail, and the apps around them.

Bots work through one command-line tool on your Mac. They text you, read and send iMessage and mail, keep your calendar, and reach the apps they have no direct line into through your notifications and your phone.

11:14
‹
JesseIdle
Dana on WhatsApp: "still on for 7 tonight?" I can't reply there myself.
say yes, 7 works👍
Wants you to send a WhatsApp messagefrom this iPhone
ToDana · +1 555 010 0142
Yes, 7 works. See you there.
Not nowOpen WhatsApp
Also, a sublet in Fort Greene came up in #housing on Discord. Want details?
Message

iMessage

Reads chats and threads, searches history, sends with your approval.

cbot messages thread --with Dana

Mail

The accounts you allow per bot, replies in thread, your sender address and signature.

cbot mail reply 4812

Calendar and Reminders

Lists, adds, moves and deletes events. Adds and completes reminders.

cbot calendar add --title "Tour" --start "2026-11-19 18:00" --minutes 45

Other apps' notifications

Wakes on what WhatsApp, Slack or Discord show on this Mac: the sender and the first line. It tells you and drafts a reply.

Wake settings → Other apps

Its own Discord bot

Give a bot a Discord bot account. It reads servers it is invited to, posts, reacts, and answers your DMs.

cbot discord send --channel #housing

Sending from your phone

SMS, WhatsApp, Telegram, Signal or email, filled in on your iPhone for you to press send.

cbot phone send --via whatsapp --to +15550100142

Buttons and reactions

Asks with 2 to 5 tap-to-answer options. Answers a "thanks" with an emoji instead of words.

cbot ask "Which tour?" --options "Thu 6pm,Sat 11am"

Your Chrome

Off by default. Browses in your signed-in Chrome through the Claude in Chrome extension.

Use my Chrome

Sub-agents

Splits work across Claude Code sub-agents. You see them orbit their bot in Mission Control.

Agent: Check listings

Each other

Bots message one another and share a board for handing off work. Allowed Shortcuts run by name.

cbot agents message --to Steve
Tue 17 Nov · 08:52 [owner · via phone] spoken Speech arrives as a normal message marked as spoken.

Talk to it. It talks back.

Tap the waveform in any conversation. Listening and speech run on your own ElevenLabs account, with a voice you pick per bot. The bot answers in short sentences, and the reply still lands in the chat as text.

ExpressiveEleven v4 Turbo

Acts on audio tags the bot adds, like a laugh or a whisper.

FastFlash v2.5

Adjustable speed. Expressive falls back to it when unavailable.

Your keyiPhone Keychain

Sent only to ElevenLabs. Usage counts against your credits.

Same botno faster

Each reply still takes the seconds a turn on the Mac takes.

Every turn --permission-mode dontAsk --allowedTools "Bash(cbot *)" … How a locked-down bot is started.

Locked down until you open it up.

A new bot can read your messages, mail, contacts, calendar and reminders. Everything else is closed until you widen it, per bot.

Locked down by default

The bot's shell can run only cbot. Files are limited to its own workspace. It can use the web and spawn sub-agents. Everything else is refused.

--allowedTools
  Bash(cbot *)
  Edit(//~/ClaudeBot/Chief/**)
  WebFetch  WebSearch
  Agent  TodoWrite

Sends need you

The send policy is enforced by the daemon inside cbot. In locked-down mode that is the bot's only route to Messages and Mail, so the policy is a real boundary.

Incoming is untrusted

Strangers can write to you, so a bot that reads your inbox reads them too. Messages from others are marked untrusted, and filters plus a quick triage check decide what wakes a bot at all.

Encrypted relay

Link the phone through iCloud or a relay you host: one PHP file. The phone scans a QR code from your Mac; messages and files are sealed with AES-GCM before upload, so the relay only stores ciphertext.

On your own Mac

Bots run on your Mac with your Claude Code login. State, chat history and workspaces stay in your home folder. Discord tokens stay on the Mac.

A budget per bot

Set a daily cap. Past it, heartbeats, schedules and watchers are held until midnight, and each mission stops at its own budget.

What the lockdown does not cover

Allow rules in your own ~/.claude/settings.json apply to the bots too. A locked-down bot still has web access, so a bot manipulated by something it read could leak what it can see in a web request. The lockdown stops it acting as you, not reading.

In full-access mode a bot could script Messages or Mail directly, so the send policy is only as strong as the bot's obedience. Keep bots that watch incoming messages locked down.

launchd · KeepAlive ClaudeBot --daemon The same app binary, run headless.

One Mac app, one daemon, one Claude Code session per bot.

The daemon wakes each bot by resuming its session with the new input, then lets the process exit. Nothing runs while a bot is idle. If a turn dies or stalls, the daemon resumes it.

How ClaudeBot fits together On your Mac, the ClaudeBot app talks to the daemon over loopback. The daemon starts one Claude Code session per bot and receives their cbot commands, then reads and sends through Messages, Mail, Contacts and EventKit. It syncs with the iPhone app through an encrypted relay or iCloud. The Claude Code sessions talk to Claude. YOUR MAC ClaudeBot.app Mission Control, chat, memory loopback RPC Daemon ClaudeBot --daemon wake-ups, schedules, missions, approvals, watchdog ONE SESSION PER BOT Steve claude -p --resume 3f9c… Jesse claude -p --resume a81e… Chief claude -p --resume 7d02… resume + input cbot … (tool.exec) READ AND SEND THROUGH Messages Mail Contacts Calendar, Reminders Notifications, Shortcuts Claude through your Claude Code login API Relay or iCloud one PHP file you host AES-GCM · stores ciphertext sync: bots, messages, commands iPhone app chats, approvals, voice push for texts and approvals
A wake-up

Your text, a heartbeat, a schedule, a tracker reply or a mission session becomes one input with a header that says where it came from.

One turn

The daemon resumes that bot's session with the input. The bot thinks, calls tools, spawns sub-agents and runs cbot. Inputs that arrive mid-turn wait for the next one.

Back to you

The bot texts you with cbot text. Sends that need approval become cards on both devices, and the bot hears the outcome later.

About 20 minutes ./scripts/setup.sh Generates the Xcode project and opens it.

Build it from source.

There is no App Store download. You build both apps with Xcode and sign them with your own Apple developer account.

You need

A Mac on macOS 14 or later with Xcode 16 or later.

An iPhone on iOS 17 or later for the phone app.

Claude Code installed and logged in, so claude works in Terminal.

A paid Apple Developer account for push notifications, and for CloudKit if you link through iCloud.

A link to the phone: your own relay (one PHP file) or iCloud.

$ git clone https://github.com/smoke-wolf/ClaudeBot.git && cd ClaudeBot && ./scripts/setup.sh
  1. Run setup

    It asks for your Team ID and a bundle prefix, such as com.yourname.claudebot, then generates ClaudeBot.xcodeproj and opens it.

  2. Build the Mac app

    Run the ClaudeBotMac scheme. Move the app to /Applications before granting permissions; macOS ties them to its location.

  3. Grant permissions from Setup

    Full Disk Access for Messages, Mail and Contacts, Automation for Messages and Mail, then Calendar and Reminders. Use the buttons in Setup.

  4. Link your phone

    Upload the relay folder to a PHP host and enter its URL in Setup, then run ClaudeBotiOS and scan the QR code. Or choose iCloud on both devices.

  5. Create a bot and text it

    From either app. It replies on your phone.

Build it from source Full setup and troubleshooting are in the README.