claude-wa

Talk to Claude Code from WhatsApp. Install, scan a QR with your phone, and your "Message yourself" chat becomes a live Claude Code console — type a message, Claude reads it and does the work, and it remembers the conversation. No PIN, no app on the server, no friction.

You ▸  what's failing in the auth tests?
🤖    The token-expiry check is off by one (`exp <= now`). Want me to fix it?
You ▸  yes, fix it and run the tests
🤖    Fixed and ran the suite — 12 passed. ✅
You ▸  commit and push
🤖    Pushed abc123 to main. ✅            ← remembers the whole thread

One Node process links to WhatsApp via the multi-device protocol (Baileys) and pipes your messages to the claude CLI.

Also in the box: 🎭 Fan mode — flip the direction and the number becomes a public AI twin your followers can DM. Pin the wa.me link in your Instagram bio and it chats with your fans in your voice, 24/7 (chat-only, hard guardrails, daily caps).

Quickstart

You need Claude Code installed and logged in (the claude command on your PATH).

$ npx claude-wa

claude-wa
  Access  : OPEN — message your self-chat, no PIN
  Mode    : ACTION (edits + shell) · remembers context
  Workdir : /home/you/project

=========  SCAN THIS QR WITH WHATSAPP  =========
  █▀▀▀▀▀█ ▄ ▀▄█ █▀▀▀▀▀█
  █ ███ █ █▀▄ ▄ █ ███ █     WhatsApp ▸ Settings ▸
  █ ▀▀▀ █ ▀ █▄▀ █ ▀▀▀ █     Linked Devices ▸ Link a device
  ▀▀▀▀▀▀▀ █▄▀▄█ ▀▀▀▀▀▀▀
  …

✅  Connected. Your WhatsApp is now a Claude Code remote.

Now open your "Message yourself" chat and just type — every message goes straight to Claude Code. No prefix needed.

# or install it for keeps
npm i -g claude-wa && claude-wa

What you can send

| Message | Does | |---------|------| | what's failing in the auth tests? | Claude investigates & answers | | fix it and run the tests | Claude edits & acts (remembers the previous message) | | !docker ps | run a raw shell command | | /new | start a fresh conversation (clears memory) | | help | show the menu |

Only your "Message yourself" chat is wired up — Claude never touches your other WhatsApp conversations.

🎭 Fan mode — your AI twin in your followers' DMs

Fan mode flips the direction: instead of you driving Claude, your audience chats with an AI persona of you. Link a WhatsApp number, pin the wa.me link in your Instagram bio, and every DM gets an in-character reply — 24/7.

$ npx claude-wa --fans

✅  Connected. This number is now a public AI persona.

   📌 Pin this in your bio:  https://wa.me/9198XXXXXXXX?text=hi
   🎭 Persona file        :  ~/.claude-wa/persona.md  (edits apply live)
   🛡  Caps               :  40/fan/day · 400 total/day · model: haiku
   🎮 Owner controls      :  message yourself  stats · pause · resume

Edit ~/.claude-wa/persona.md — name, vibe, what to plug — and the bot picks it up on the next message, no restart.

Built-in guardrails (this is strangers on the internet, so fan mode is locked down hard):

• Chat only, zero tools — no shell, no file access, and prompt-injection refusals stay in character.
• Per-fan memory — each fan gets their own conversation thread.
• Daily caps — per-fan and global (CLAUDE_WA_FAN_DAILY_CAP, CLAUDE_WA_FAN_GLOBAL_CAP) so API spend can't run away.
• Groups/status ignored; your own outgoing messages are never treated as prompts, so you can always jump into a chat yourself.
• Owner controls from your self-chat: stats, pause, resume.

Modes

Open (default) — no PIN, self-chat is the console, conversation memory on.

Read-only — claude-wa --read-only. Claude can read & answer but the Edit/Write/Bash tools aren't granted; nothing on the machine changes.

PIN — claude-wa --pin. Restores the "<PIN> <message>" prefix and lets you drive from allow-listed chats too (--allow 9199...). Use this if the number is shared or you want a second factor.

Options

--fans               Fan mode: public AI persona for anyone who DMs the number
--persona <file>     Persona instructions for fan mode (default: ~/.claude-wa/persona.md)
--fan-model <m>      Model for fan replies (default: haiku — fast & cheap)
--read-only          Read & answer only — no edits, no shell
--no-continue        Each message is a fresh, standalone prompt (no memory)
--pin [value]        Opt into PIN mode (value optional; auto-generated if omitted)
--allow <nums>       Also accept these numbers (comma-separated)
--chat <number>      Bind the console to a specific chat instead of self-chat
--any-chat           Accept ANY chat (⚠ Claude replies everywhere)
--workdir <dir>      Directory Claude runs in (default: current dir)
--claude-bin <path>  Path to the claude binary (default: claude on PATH)
--no-shell           Disable the  !cmd  shortcut
--pair <phone>       Link via pairing code instead of QR (digits only)
--accept-trust       Trust Claude Code for the workdir, then exit (run once)
-h, --help · -v, --version

Also configurable via env (CLAUDE_WA_READONLY=1, CLAUDE_WA_PIN, CLAUDE_WA_ALLOW, CLAUDE_WA_WORKDIR, CLAUDE_WA_NO_CONTINUE=1, …) and persisted to ~/.claude-wa/config.json. WhatsApp auth lives in ~/.claude-wa/auth/.

Trust

Action mode needs a trusted workspace, and you can't accept a terminal dialog from your phone — so claude-wa auto-trusts the working directory on startup (running it there is the consent). To pre-trust without starting:

claude-wa --accept-trust --workdir /path/to/project

Security

In action mode, anyone who can send to the wired-up chat can run Claude Code — including shell — on this machine. In open mode the gate is simply access to your WhatsApp.

• Run in a dedicated --workdir, ideally as a non-root user.
• Use --read-only if you don't want a text to change anything.
• Use --pin to add a secret second factor (and to drive from other chats).
• Long jobs (> ~150s) get the claude process killed by the timeout — use a real session for big multi-step work; texts are best for quick asks and fixes.

Heads-up: claude-wa links via an unofficial WhatsApp library (Baileys), which is against WhatsApp's Terms of Service. Use a number you're willing to risk; automated accounts can be rate-limited or banned. Provided as-is, no warranty.

Keep it running

It runs in the foreground. To keep it alive across logout/reboot, use any process manager:

# nohup
nohup claude-wa --workdir ~/myproject > ~/claude-wa.log 2>&1 &

# pm2
pm2 start claude-wa -- --workdir ~/myproject

# systemd (sketch) — ExecStart=/usr/bin/claude-wa --workdir /srv/app

Troubleshooting

• No reply after texting? In open mode, make sure you're texting your own "Message yourself" chat. The console logs each linked identity on connect; if the self-chat isn't auto-detected it binds to the first chat you message.
• Connection drops / "failed to decrypt" right after linking: restart claude-wa once — a fresh link heals the WhatsApp/Signal session.
• claude binary not found: install Claude Code or pass --claude-bin /full/path/to/claude.

How it works

WhatsApp  ──(Baileys multi-device)──►  claude-wa  ──spawn──►  claude -p [--continue]
   ▲                                       │
   └────────────── reply ◄─────────────────┘

claude runs headless with --permission-mode acceptEdits --allowedTools … (not --dangerously-skip-permissions, which the CLI blocks under root), the prompt is fed on stdin, and --continue is added after the first message so the conversation has memory.

License

MIT © Dark Lord