ClaudeClaw

 ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
██║     ██║     ███████║██║   ██║██║  ██║█████╗
██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝
╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗
 ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝╚══════╝

 ██████╗██╗      █████╗ ██╗    ██╗
██╔════╝██║     ██╔══██╗██║    ██║
██║     ██║     ███████║██║ █╗ ██║
██║     ██║     ██╔══██║██║███╗██║
╚██████╗███████╗██║  ██║╚███╔███╔╝
 ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝

Your Claude Code CLI, delivered to your phone via Telegram.

ClaudeClaw is not a chatbot wrapper. It spawns the actual claude CLI on your Mac or Linux machine and pipes the result back to your Telegram chat. Everything that works in your terminal (your skills, your tools, your context) works from your phone.

Get started

ClaudeClaw setup flow

Follow these steps in order. The whole thing takes about 5 minutes.

Step 1: What you need before anything else

| Requirement | Notes | |-------------|-------| | Node.js 20+ | Check: node --version. Download at nodejs.org | | Git | Check: git --version. If you've never used git, also run the two commands below | | Claude Code CLI | Install: npm i -g @anthropic-ai/claude-code | | Claude account | Log in: claude login (free, Pro, or Max plan) | | Telegram account | Any existing account works |

First time using git? Run these two commands first (use your own name and email):

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Without this, git operations will fail with a confusing error about missing identity.

macOS users: After starting ClaudeClaw for the first time, your Mac may show "Node wants to access..." permission dialogs. You need to click Allow on each one or the bot will silently hang. Keep an eye on your Mac screen during the first run.

Which Claude plan works best? ClaudeClaw runs the claude CLI, so any plan works (Free, Pro, Max). However, complex multi-step tasks (building skills, debugging code, multi-agent work) perform significantly better on Opus: If you're on the Free or Pro plan and Claude struggles with a task, the model matters. Sonnet is fast but often can't handle the kind of agentic work ClaudeClaw enables. Max ($100 or $200) with Opus is the recommended experience.

New to the terminal? Download Warp, it's a modern terminal with AI built in. If you hit any OS-level issues during setup (permissions, missing tools, PATH problems), type /agent in Warp and describe what went wrong. It will walk you through fixing it. This alone will save you hours of Googling.

That's it for hard requirements. Everything else (voice, video, WhatsApp) is optional and the setup wizard will ask about them.

Step 2: Create a Telegram bot

You need a bot token from Telegram. This is what ClaudeClaw uses to send and receive messages.

Open Telegram and search for @BotFather
Send /newbot
Follow the prompts, give it a name and a username (e.g. MyAssistantBot)
Copy the token BotFather gives you, it looks like 1234567890:AAFxxxxxxx

Keep this token handy for the next step.

Step 3: Clone and install

git clone https://github.com/earlyaidopters/claudeclaw.git
cd claudeclaw
npm install

Step 4: Run the setup wizard

npm run setup

The wizard walks you through everything interactively:

Checks your environment (Node, Claude CLI, builds if needed)
Asks which features you want (voice input, voice output, video analysis, WhatsApp)
Sets up your Telegram bot token and chat ID
Configures security: PIN lock, emergency kill phrase, idle auto-lock
Opens your editor to personalize CLAUDE.md
Lists the skills you'll want to install and where to get them
Prompts for API keys only for the features you selected
Installs a background service (launchd on macOS, systemd on Linux, PM2 on Windows)

Prefer to let Claude handle it? After cloning, cd into the repo, run claude, and paste:
I just cloned ClaudeClaw. Please read README.md and set me up completely.
install deps, configure .env, help me get any API keys I need, and set up
the background service for my OS.

Step 5: Get your Telegram chat ID

Your chat ID locks the bot to you, no one else can use it.

Start the bot: npm start
Open Telegram and message your bot
Send /chatid
The bot replies with a number. that's your chat ID
Add it to .env:
```
ALLOWED_CHAT_ID=your_number_here
```
Restart: stop the bot (Ctrl+C) and run npm start again

The setup wizard does this step automatically if you run npm run setup before starting.

Step 6: Send your first message

With the bot running, send any message. Try:

What can you do?

Check my calendar for today

or just start talking. Claude Code is running on your machine, it has access to your files, the web, and every skill you've installed.

Step 7: Run as a background service

You probably want ClaudeClaw running automatically, not manually in a terminal.

macOS: the setup wizard installs a launchd agent. Or manually:

# After running npm run setup, it's already installed.
# Logs:
tail -f /tmp/claudeclaw.log

Linux: the setup wizard installs a systemd user service:

systemctl --user status claudeclaw
journalctl --user -u claudeclaw -f

Windows: use WSL2 (recommended) and follow the Linux steps, or:

npm install -g pm2
pm2 start dist/index.js --name claudeclaw
pm2 save && pm2 startup

Step 8: Check everything is healthy

npm run status

Output looks like:

  ✓  Node v22.3.0
  ✓  Claude CLI 1.0.12
  ✓  Bot token: @YourBotName
  ✓  Chat ID: 1234567890
  ✓  Voice STT: Groq (configured)
  ⚠  Voice TTS: not configured
  ✓  Service: running (PID 12345)
  ✓  Memory DB: 47 memories stored
  ─────────────────
  All systems go.

Updating ClaudeClaw

When a new version is released, update in 5 commands:

cd claudeclaw          # go to your ClaudeClaw directory
git pull               # pull the latest code
npm install            # install any new dependencies
npm run migrate        # apply any pending migrations
npm run build          # recompile TypeScript

Then restart the bot (Ctrl+C and npm start, or restart the background service).

Do not point Claude at the GitHub URL to read updates. Claude works with local files, so you need the repo cloned on your machine. git pull is how you stay current.

Upgrading from V1? If you heavily customized V1, start fresh with V2 and copy over your .env and any CLAUDE.md customizations. If you kept V1 mostly stock, git pull will work.

How it works

ClaudeClaw architecture

What's included

Zero extra API keys needed

With just TELEGRAM_BOT_TOKEN and ALLOWED_CHAT_ID:

| Feature | Works? | Notes | |---------|--------|-------| | Text messaging | ✅ | Full Claude Code, all tools | | Photos | ✅ | Claude reads and analyzes them | | Documents | ✅ | PDF, code, text. anything Claude Code can open | | SQLite memory | ✅ | Auto-initialized on first run, nothing to configure | | Session persistence | ✅ | Context carries across every message | | Scheduled tasks | ✅ | Ask Claude to run anything on a cron schedule | | Mission Control | ✅ | Dashboard task board with auto-assign. Needs GOOGLE_API_KEY for auto-assign | | Web dashboard | ✅ | Live monitoring via Cloudflare tunnel. Needs DASHBOARD_TOKEN | | Multi-agent | ✅ | Run multiple specialized agents in parallel | | All your skills | ✅ | Every skill in ~/.claude/skills/ auto-loads | | WhatsApp (/wa) | ✅ | No API key, but needs the wa-daemon running | | Voice input | ❌ | Needs GROQ_API_KEY | | Voice output (macOS) | ✅ | Uses say + ffmpeg locally, no API key needed | | Voice output (cloud) | ❌ | ElevenLabs or Gradium API key for higher quality | | Video analysis | ❌ | Needs GOOGLE_API_KEY + gemini-api-dev skill | | Memory consolidation | ❌ | Needs GOOGLE_API_KEY for Gemini-powered pattern detection |

API keys: what each does and alternatives

Telegram Bot Token (required)

Get it: @BotFather → /newbot. free, instant.

Groq: voice input (optional)

What it does: Transcribes your voice notes using Whisper before passing them to Claude.

Get it: console.groq.com. free tier, no card needed.

Model: whisper-large-v3

| Alternative | Cost | Notes | |-------------|------|-------| | Groq (default) | Free | Fastest to set up | | OpenAI Whisper | ~$0.006/min | Swap transcribeAudio() in src/voice.ts | | AssemblyAI | Free tier | More features | | Local Whisper.cpp | Free | No API, runs on your Mac. needs code change |

ElevenLabs: voice output (optional)

What it does: Converts Claude's responses to audio in your cloned voice.

Get it: elevenlabs.io → clone your voice under "Voice Lab" → copy the Voice ID string.

Model: eleven_turbo_v2_5

Tuning: Edit src/voice.ts if the cloned voice sounds off:

stability: 0.5        (higher = more consistent but robotic)
similarity_boost: 0.75  (higher = closer to you but can distort)

| Provider | Cost | Notes | |----------|------|-------| | ElevenLabs (primary) | Free tier + paid | Best cloning quality | | Gradium AI (built-in alternative) | Free tier (45k credits/mo) | Add GRADIUM_API_KEY + GRADIUM_VOICE_ID to .env | | macOS say + ffmpeg (built-in fallback) | Free | No API key. works offline. Set TTS_VOICE in .env to change voice | | OpenAI TTS | ~$0.015/1k chars | Good quality, no cloning. needs code change | | Google Cloud TTS | Free tier |

Claudeclaw

Install / Use

README