Files

gavrielc c17823a732 Initial commit: NanoClaw - Personal Claude assistant via WhatsApp

A minimal Node.js application that connects Claude Agent SDK to WhatsApp
using baileys. Features per-group memory via CLAUDE.md files, session
continuity, scheduled tasks, and Gmail integration via MCP.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-31 18:54:24 +02:00

3.3 KiB

Raw Blame History

NanoClaw Requirements

Original requirements and design decisions from the project creator.

Vision

A personal Claude assistant accessible via WhatsApp, with minimal custom code.

Core components:

Claude Agent SDK as the core agent
WhatsApp as the primary I/O channel
Persistent memory per conversation and globally
Scheduled tasks that run Claude and can message back
Web access for search and browsing

Design philosophy:

Leverage existing tools (WhatsApp connector, Claude Agent SDK, MCP servers)
Minimal glue code
File-based systems where possible (CLAUDE.md for memory, folders for groups)

Architecture Decisions

Message Routing

A router listens to WhatsApp and routes messages based on configuration
Only messages from registered groups are processed
Trigger: @Andy prefix (case insensitive), configurable via ASSISTANT_NAME env var
Unregistered groups are ignored completely

Memory System

Per-group memory: Each group has a folder with its own CLAUDE.md
Global memory: Root CLAUDE.md is read by all groups, but only writable from "main" (self-chat)
Files: Groups can create/read files in their folder and reference them
Agent runs in the group's folder, automatically inherits both CLAUDE.md files

Session Management

Each group maintains a conversation session (via Claude Agent SDK)
/clear command resets the session but keeps memory files
Old session IDs are archived to a file

Scheduled Tasks

Users can ask Claude to schedule cron jobs from any group
Tasks run in the context of the group that created them (with that group's memory)
Task output is logged to the group's folder

Group Management

New groups are added explicitly via the main channel
Groups are identified by human-readable name when possible
Each group gets a dedicated folder

Integration Points

Using baileys library for WhatsApp Web connection
Messages stored in SQLite, polled by router
QR code authentication during setup

Email (Gmail)

Read-only MCP integration (can read and send, but not an I/O channel)
Optional, enabled during setup

Scheduler

MCP server for creating/managing scheduled tasks
Tasks execute Claude Agent SDK in group context

Web Access

Built-in WebSearch and WebFetch tools
Standard Claude Agent SDK capabilities

Setup & Customization

Philosophy

Minimal configuration files
Setup and customization done via Claude Code
Users clone the repo and run Claude Code to configure
Each user gets a custom setup matching their exact needs

Skills

/setup - Install dependencies, authenticate WhatsApp/Gmail, configure scheduler, start services
/customize - General-purpose skill for adding capabilities (new channels like Telegram, new integrations, behavior changes)

Deployment

Runs on local Mac via launchd
Single Node.js process handles everything

Personal Configuration (Reference)

These are the creator's settings, stored here for reference:

Trigger: @Andy (case insensitive)
Response prefix: Andy:
Persona: Default Claude (no custom personality)
Gmail: Enabled
Main channel: Self-chat (messaging yourself in WhatsApp)

Project Name

NanoClaw - A reference to Clawdbot (now OpenClaw).

3.3 KiB Raw Blame History