09c0e8142e
- Agents run in isolated Linux VMs via Apple Container - All groups get Bash access (safe - sandboxed in container) - Browser automation via agent-browser + Chromium - Per-group configurable additional directory mounts - File-based IPC for messages and scheduled tasks - Container image with Node.js 22, Chromium, agent-browser Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
142 lines
5.0 KiB
Markdown
142 lines
5.0 KiB
Markdown
# 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).
|