A personal AI assistant that runs on your messaging platforms. Send a message on WhatsApp, Telegram, Signal, or iMessage and get responses from Claude with full tool access, persistent memory, scheduled reminders, browser automation, and integrations with 500+ apps.

• Requirements
• Installation
• Quick Start
• Configuration
• Messaging Platforms
  • WhatsApp
  • Telegram
  • Signal
  • iMessage
• Browser Control
  • Clawd Mode
  • Chrome Mode
• Memory System
• Scheduling and Reminders
• App Integrations
• Commands
  • CLI Commands
  • Chat Commands
• Troubleshooting

---

• Node.js 18 or higher
• macOS, Linux, or Windows
• An Anthropic API key (set as ANTHROPIC_API_KEY environment variable)
• A Composio API key (set as COMPOSIO_API_KEY environment variable)

For specific adapters:

• WhatsApp: A phone with WhatsApp installed
• Telegram: A bot token from @BotFather
• Signal: signal-cli installed and registered
• iMessage: macOS with Messages.app signed in, plus the imsg CLI tool

---

cd clawd
npm install

You need two API keys: one from Anthropic and one from Composio.

Anthropic API Key:

Get your API key from https://console.anthropic.com/

export ANTHROPIC_API_KEY=sk-ant-...

Composio API Key:

Composio provides the app integrations (Gmail, Slack, GitHub, etc.). You need to install the Composio CLI and log in to get your API key.

1. Install the Composio CLI:

curl -fsSL https://composio.dev/install | bash

2. Log in (this opens your browser):

composio login

3. Get your API key:

composio whoami

Look for the line showing API Key: ... and copy it.

4. Set the environment variable:

export COMPOSIO_API_KEY=your-api-key-here

Making Keys Permanent:

Add both exports to your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile):

echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
echo 'export COMPOSIO_API_KEY=...' >> ~/.zshrc
source ~/.zshrc

---

Run the CLI:

node cli.js

You will see a menu:

What would you like to do?

  1) Terminal chat
  2) Start gateway
  3) Setup adapters
  4) Configure browser
  5) Show current config
  6) Test connection
  7) Exit

Terminal chat lets you test the assistant directly in your terminal before connecting any messaging platforms.

Start gateway runs the full system, connecting to all enabled messaging platforms and listening for messages.

---

All settings are in config.js. You can edit this file directly or use the setup wizard (node cli.js then select option 3 for adapters or option 4 for browser).

The configuration includes:

{
  agentId: 'clawd',              // Unique identifier for your assistant

  whatsapp: { enabled: true, ... },
  telegram: { enabled: false, token: '', ... },
  signal: { enabled: false, phoneNumber: '', ... },
  imessage: { enabled: false, ... },

  agent: {
    workspace: '~/clawd',        // Where memory and files are stored
    maxTurns: 50,                // Max tool calls per message
    allowedTools: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep']
  },

  browser: {
    enabled: true,
    mode: 'clawd',               // 'clawd' or 'chrome'
    ...
  }
}

---

WhatsApp uses QR code authentication. No additional setup required beyond enabling it in config.

1. Enable WhatsApp in config or run the setup wizard
2. Start the gateway: node cli.js then select "Start gateway"
3. A QR code will appear in your terminal
4. Open WhatsApp on your phone, go to Settings > Linked Devices > Link a Device
5. Scan the QR code

Your session is saved in auth_whatsapp/. You only need to scan once unless you log out.

Configuration options:

whatsapp: {
  enabled: true,
  allowedDMs: ['*'],           // '*' allows all direct messages
  allowedGroups: [],           // Add group JIDs to allow specific groups
  respondToMentionsOnly: true  // In groups, only respond when @mentioned
}

You need a bot token from Telegram's BotFather.

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token (looks like 123456789:ABCdefGHIjklmno...)
4. Run the setup wizard or add the token to config:

telegram: {
  enabled: true,
  token: 'YOUR_BOT_TOKEN',
  allowedDMs: ['*'],
  allowedGroups: [],
  respondToMentionsOnly: true
}

Start the gateway and message your bot on Telegram.

Signal requires the signal-cli tool to be installed and registered.

1. Install signal-cli: https://github.com/AsamK/signal-cli
2. Register your phone number:

   signal-cli -u +1234567890 register
   signal-cli -u +1234567890 verify CODE
   

3. Configure in config.js:

signal: {
  enabled: true,
  phoneNumber: '+1234567890',
  signalCliPath: 'signal-cli',  // or full path to the binary
  allowedDMs: ['*'],
  allowedGroups: [],
  respondToMentionsOnly: true
}

iMessage only works on macOS and requires the imsg CLI tool.

1. Make sure you are signed into Messages.app on your Mac
2. Install imsg:

   brew install steipete/formulae/imsg
   

   Or download from: https://github.com/steipete/imsg
3. Enable in config:

imessage: {
  enabled: true,
  allowedDMs: ['*'],
  allowedGroups: [],
  respondToMentionsOnly: true
}

---

Clawd can control a web browser to navigate pages, click buttons, fill forms, and take screenshots. There are two modes:

This launches a dedicated Chromium browser with its own profile. Your browsing data is kept separate from your personal browser.

Setup:

1. Run node cli.js and select "Configure browser"
2. Select "clawd - Managed browser"
3. When prompted, allow it to install Playwright's Chromium browser
4. Choose a profile path or accept the default (~/.clawd-browser-profile)
5. Choose whether to run headless (no visible window)

The browser will launch automatically when you start the gateway or terminal chat.

When to use this mode:

• You want a clean, isolated browsing environment
• You do not need existing login sessions
• You want to see exactly what the assistant is doing

This connects to your existing Chrome browser, giving the assistant access to your logged-in sessions. Useful when you need the assistant to interact with sites where you are already authenticated.

Setup:

1. Run node cli.js and select "Configure browser"
2. Select "chrome - Control your Chrome"
3. Note the CDP port (default 9222)

Before starting the gateway, you must launch Chrome with remote debugging enabled:

macOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Linux:

google-chrome --remote-debugging-port=9222

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Then start the gateway. The assistant will connect to your running Chrome instance.

When to use this mode:

• You need the assistant to use your logged-in sessions (Gmail, GitHub, etc.)
• You want to watch and interact with the same browser the assistant controls

Security note: This mode gives the assistant access to all your open tabs and logged-in sessions. Only use with sites you trust the assistant to access.

Once browser is enabled, the assistant can:

• browser_navigate - Go to a URL
• browser_snapshot - Get the page structure (accessibility tree)
• browser_screenshot - Take a screenshot
• browser_click - Click elements
• browser_type - Type into input fields
• browser_press - Press keyboard keys
• browser_tabs - List open tabs
• browser_switch_tab - Switch between tabs
• browser_new_tab / browser_close_tab - Manage tabs
• browser_back / browser_forward / browser_reload - Navigation

---

Clawd maintains persistent memory across conversations. All memory is stored in the workspace directory (default: ~/clawd/).

• MEMORY.md - Long-term memory for important facts, preferences, and decisions
• memory/YYYY-MM-DD.md - Daily notes, one file per day

The assistant automatically loads recent memory at the start of each conversation:

• Long-term memory (MEMORY.md)
• Yesterday's notes
• Today's notes

When you tell the assistant to remember something, it decides whether to:

• Add to MEMORY.md (permanent facts, preferences)
• Add to today's daily log (temporary notes, tasks completed)

"Remember that my favorite coffee shop is Blue Bottle on Market Street"

• This goes to MEMORY.md

"Remember that I called the dentist today"

• This goes to today's daily log

Use the /memory command in chat to see current memory, or /memory list to see all memory files.

---

The assistant can schedule messages to be sent later.

"Remind me in 30 minutes to check the oven" "Send me a message in 2 hours about the meeting"

"Remind me every day at 9am to take my vitamins" "Send me a status update every hour"

For advanced scheduling, the assistant can use cron expressions:

• 0 9 * * * - Every day at 9:00 AM
• 0 9 * * 1-5 - Weekdays at 9:00 AM
• 30 14 * * 1 - Every Monday at 2:30 PM

Scheduled jobs persist across restarts and are stored in ~/.clawd/cron-jobs.json.

---

Clawd includes Composio integration, providing access to 500+ apps including:

• Gmail, Google Calendar, Google Sheets, Google Drive
• Slack, Discord
• GitHub, GitLab, Jira, Linear
• Notion, Trello, Asana
• Salesforce, HubSpot
• Twitter/X, LinkedIn
• And many more

Just ask the assistant to do something with an app:

"Send an email to john@example.com about the project update" "Create a GitHub issue for the login bug" "Add an event to my calendar for tomorrow at 3pm"

The first time you use an app, Composio will provide an authentication link. Click it to authorize access, then the assistant can use that app.

---

Run these from your terminal:

node cli.js              # Interactive menu
node cli.js chat         # Start terminal chat directly
node cli.js start        # Start the gateway directly
node cli.js setup        # Run the setup wizard
node cli.js config       # Show current configuration
node cli.js help         # Show help

Or if you link the package globally:

npm link
clawd              # Interactive menu
clawd chat         # Terminal chat
clawd start        # Start gateway

Use these commands while chatting with Clawd on any platform:

Command	Description
/new or /reset	Start a fresh conversation, clearing context
/status	Show session information
/memory	Show current memory summary
/memory list	List all memory files
/memory search <query>	Search through memories
/queue	Show message queue status
/stop	Stop the current operation
/help	Show available commands

---

Set your API key as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

Make sure your Composio API key is set:

export COMPOSIO_API_KEY=your-api-key

If you do not have an API key:

curl -fsSL https://composio.dev/install | bash
composio login
composio whoami   # Shows your API key

You can also check your Composio dashboard at https://app.composio.dev

Delete the auth_whatsapp/ folder and restart the gateway to force a new authentication.

Run the browser setup again and make sure Playwright's Chromium is installed:

npx playwright install chromium

Make sure Chrome is running with remote debugging enabled before starting the gateway:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Check that the port in your config matches the port Chrome is using.

• Verify your bot token is correct
• Make sure you have started a conversation with your bot (send /start)
• Check that enabled: true is set in the telegram config

• Verify signal-cli is installed and in your PATH
• Make sure your phone number is registered and verified
• Check the phone number format includes country code (e.g., +1234567890)

• Only works on macOS
• Make sure Messages.app is open and signed in
• Verify imsg is installed: which imsg
• Grant terminal/application accessibility permissions if prompted

Check that the workspace directory exists and is writable:

ls -la ~/clawd/

If it does not exist, it will be created automatically on first use.

• Jobs persist in ~/.clawd/cron-jobs.json
• Jobs only execute while the gateway is running
• Use /memory list in chat to check scheduled jobs

---

clawd/
  config.js           # Configuration file
  cli.js              # CLI entry point
  gateway.js          # Main gateway process
  adapters/           # Messaging platform adapters
    whatsapp.js
    telegram.js
    signal.js
    imessage.js
  agent/              # Claude agent implementation
    claude-agent.js
    runner.js
  browser/            # Browser control
    server.js
    mcp.js
  memory/             # Memory management
    manager.js
  tools/              # Built-in tools
    cron.js
  commands/           # Slash command handlers
    handler.js
  sessions/           # Session management
    manager.js
  auth_whatsapp/      # WhatsApp auth (created on first run)

~/clawd/              # Workspace (created on first run)
  MEMORY.md           # Long-term memory
  memory/             # Daily logs
    2025-01-28.md
    ...

---

MIT