🦞 a claw for your voice 🦞
Hold a button. Say what you need. It gets done.

---

🔥 What is VoiceClaw?

VoiceClaw is a voice-first AI agent that handles your entire digital life — email, calendar, texts, notes, web browsing, and more — using only your voice.

Imagine calling someone who's sitting at your computer at home. That's VoiceClaw. 🦞

You're driving. You're walking. You can't look at your phone. Just hold a button, tell VoiceClaw what you need, and it actually does it — sends the email, creates the calendar invite, texts your cofounder, checks your grades, orders food. Whatever.

Zero windows. Zero popups. Zero interruptions. Everything happens invisibly.

---

🚀 What it can do

📧 Communication	📅 Productivity	🌐 Web & Media
✉️ Read & send Gmail (3 accounts)	📆 Check & create calendar events	🔍 Web search (Brave)
💬 Read & send iMessages	📝 Apple Notes & Reminders	🎵 Spotify control
💼 Read Outlook inbox	👥 Contact lookup (275+ contacts)	🔗 Browse LinkedIn, X, Alma
🦞 OpenClaw channels (WhatsApp, Telegram, Slack, Discord, Signal)	⏰ Scheduled recurring tasks	📂 File search via Spotlight
✍️ Draft outreach (2-3 variants!)	🧠 Persistent memory across sessions	📸 Screenshots, clipboard
🎯 Smart email routing (personal/work/school)	🔔 VIP message alerts	🏠 System controls

---

⚡ Quick start

# 1. Setup (one time — checks deps, permissions, creates Chrome profile)
cd ~/voiceclaw
bash setup.sh

# 2. Create your personal config files (gitignored)
cp user_context.example.md user_context.md
cp .mcp.example.json .mcp.json
cp schedules.example.json schedules.json

# 3. Run!
python3 cli.py        # 🖥️  CLI mode — type tasks
python3 voiceclaw.py  # 🎙️  Voice mode — hold right ⌘ to talk

🦞 Notification icon fix

By default, macOS notifications show the terminal-notifier icon. To show the VoiceClaw lobster logo instead:

# Replace terminal-notifier's icon with VoiceClaw logo
cd ~/voiceclaw

# Generate .icns from logo
mkdir -p /tmp/vc_icon.iconset
for size in 16 32 64 128 256 512 1024; do
  sips -z $size $size logo.png --out /tmp/vc_icon.iconset/icon_${size}x${size}.png 2>/dev/null
done
cp /tmp/vc_icon.iconset/icon_1024x1024.png /tmp/vc_icon.iconset/icon_512x512@2x.png
cp /tmp/vc_icon.iconset/icon_64x64.png /tmp/vc_icon.iconset/icon_32x32@2x.png
iconutil -c icns /tmp/vc_icon.iconset -o /tmp/VoiceClaw.icns

# Replace icon and rename app
TN_APP="$(brew --prefix)/Cellar/terminal-notifier/$(brew list --versions terminal-notifier | awk '{print $2}')/terminal-notifier.app"
cp "$TN_APP/Contents/Resources/Terminal.icns" "$TN_APP/Contents/Resources/Terminal.icns.bak"
cp /tmp/VoiceClaw.icns "$TN_APP/Contents/Resources/Terminal.icns"
/usr/libexec/PlistBuddy -c 'Set :CFBundleName VoiceClaw' "$TN_APP/Contents/Info.plist"
/usr/libexec/PlistBuddy -c 'Set :CFBundleDisplayName VoiceClaw' "$TN_APP/Contents/Info.plist"

# Clear icon cache (may need logout/login for full effect)
touch "$TN_APP"
killall NotificationCenter 2>/dev/null

Then go to System Settings > Notifications and make sure VoiceClaw (formerly terminal-notifier) is set to Banners.

---

🎙️ Voice mode

Hold right command — a waveform appears on the right edge of your screen, driven by your actual mic input. Let go, and WhisperKit transcribes locally on-device. Your task gets queued and executed by the agent.

Say things like:

• "Email Philip saying we should hop on a call tomorrow at 3"
• "What's on my calendar today?"
• "Text mom I'll be home by 6"
• "Add a reminder to submit the ISEF forms by Friday"
• "Check my last 5 emails"
• "Play some focus music"
• "Look up the best pizza near Thetford"

---

🖥️ CLI mode

  🦞 voiceclaw  v0.2
  openclaw: whatsapp, imessage, telegram
  mcp: memory, brave-search, filesystem

────────────────────────────────────────────────
❯ send an email to philip about the pitch deck

  ⠹ Thinking
  ▸ contacts.sh search "Philip"
  ▸ gmail compose → philipmeng8@gmail.com

  ⎿  Sent from elijah@shepherdhealth.ai to Philip
  ⎿  Subject: "pitch deck updates"

  🦞 8s · 3t · $0.012
────────────────────────────────────────────────
❯

---

🧠 How it works

🎙️ Voice Input          🖥️ CLI Input
     │                       │
     ▼                       ▼
 WhisperKit              Text prompt
     │                       │
     └───────┬───────────────┘
             ▼
     📋 Daily Brief injected
     (calendar + email + messages + browsing + reminders)
             │
             ▼
     🤖 Claude Sonnet Agent
     (stealth AppleScript, headless Chrome CDP, sqlite, shell, MCP tools)
             │
     ┌───────┼───────┬──────────┬──────────┐
     ▼       ▼       ▼          ▼          ▼
   📧      📅      💬        🌐        🦞
  Gmail  Calendar  iMessage  Chrome   OpenClaw
  (API)  (osascript) (sqlite) (CDP)  (channels)

Everything is headless. A hidden Chrome instance runs on localhost:9222 with your saved sessions. AppleScript commands go through stealth.sh which saves your focus, runs the command, hides the app, and restores focus — all in milliseconds.

---

🦞 OpenClaw integration

VoiceClaw optionally integrates with OpenClaw for cross-platform messaging:

npm install -g openclaw
openclaw configure
openclaw plugins enable whatsapp
openclaw gateway  # start the gateway

When the gateway is running, VoiceClaw can send and read messages across WhatsApp, Telegram, Discord, Slack, Signal, iMessage, and more.

---

📁 Architecture

voiceclaw/
├── cli.py                 # CLI REPL — persistent session, multi-turn
├── voiceclaw.py           # macOS app — voice recording, task queue, edge indicator
├── agent/
│   ├── client.py          # Claude Agent SDK + MCP servers
│   ├── system_prompt.py   # Agent brain — tools, rules, routing
│   ├── sync.py            # Context sync (calendar, email, iMessage, history)
│   ├── renderer.py        # CLI output (spinner, shimmer, tool display)
│   ├── openclaw.py        # OpenClaw CLI wrapper
│   ├── schedule.py        # Cron-based recurring tasks
│   ├── monitor.py         # VIP message & calendar alerts
│   ├── chrome_bg.py       # Hidden Chrome on CDP port 9222
│   ├── stealth.sh         # Zero-interruption AppleScript wrapper
│   ├── contacts.sh        # Instant contact lookup via sqlite
│   └── user_context.py    # User profile loader
├── user_context.md        # Your profile, contacts, communication rules
├── .daily_brief.md        # Auto-synced daily context snapshot
├── tasks.md               # Voice task queue
└── setup.sh               # One-time setup + permission checker

---

🔒 Privacy

• All voice transcription happens locally via WhisperKit — audio never leaves your machine
• Contacts, messages, and calendar data are read from local databases (sqlite)
• The hidden Chrome profile stays on your machine at ~/.voiceclaw_chrome_profile
• Personal config files are .gitignored — never committed
• Agent runs via Claude API — prompts are sent to Anthropic's servers

---

Built on the Claude Agent SDK
Part of the OpenClaw ecosystem 🦞