Regolith/REQUIREMENTS.md

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
• Apple Container for isolated agent execution (Linux VMs)
• 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
• Browser automation via agent-browser

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

Container Isolation

• All agents run inside Apple Container (lightweight Linux VMs)
• Each agent invocation spawns a container with mounted directories
• Containers provide filesystem isolation - agents can only see mounted paths
• Bash access is safe because commands run inside the container, not on the host
• Browser automation via agent-browser with Chromium in the container

Scheduled Tasks

• Users can ask Claude to schedule recurring or one-time tasks from any group
• Tasks run as full agents in the context of the group that created them
• Tasks have access to all tools including Bash (safe in container)
• Tasks can optionally send messages to their group via send_message tool, or complete silently
• Task runs are logged to the database with duration and result
• Schedule types: cron expressions, intervals (ms), or one-time (ISO timestamp)
• From main: can schedule tasks for any group, view/manage all tasks
• From other groups: can only manage that group's tasks

Group Management

• New groups are added explicitly via the main channel
• Groups are registered by editing data/registered_groups.json
• Each group gets a dedicated folder under groups/
• Groups can have additional directories mounted via containerConfig

Main Channel Privileges

• Main channel is the admin/control group (typically self-chat)
• Can write to global memory (groups/CLAUDE.md)
• Can schedule tasks for any group
• Can view and manage tasks from all groups
• Can configure additional directory mounts for any group

---

Integration Points

WhatsApp

• 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

• Built-in scheduler runs on the host, spawns containers for task execution
• Custom nanoclaw MCP server (inside container) provides scheduling tools
• Tools: schedule_task, list_tasks, pause_task, resume_task, cancel_task, send_message
• Tasks stored in SQLite with run history
• Scheduler loop checks for due tasks every minute
• Tasks execute Claude Agent SDK in containerized group context

Web Access

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

Browser Automation

• agent-browser CLI with Chromium in container
• Snapshot-based interaction with element references (@e1, @e2, etc.)
• Screenshots, PDFs, video recording
• Authentication state persistence

---

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).