NuClaw - Personal Claude Assistant

A personal Claude assistant that runs securely in isolated containers.

English | 简体中文

Why Rust?

Performance - Faster startup and lower memory usage
Safety - Memory safety and thread safety guarantees
Concurrency - Better async handling for I/O operations

Features

WhatsApp I/O - Message Claude from your phone
Telegram I/O - Message Claude from Telegram
Isolated group context - Each group has its own memory and filesystem
Container isolation - Agents run in Docker or Apple Container
Scheduled tasks - Recurring jobs with cron expressions
Mount allowlist - Secure additional mount validation

Architecture

WhatsApp / Telegram → SQLite → Scheduler → Container (Claude Agent SDK) → Response

System Architecture

flowchart TB
    subgraph Input["Input Layer"]
        WA[WhatsApp MCP]
        TG[Telegram Bot API]
    end

    subgraph Core["Core Layer"]
        Main[Main Application]
        DB[(SQLite Database)]
        TS[Task Scheduler]
    end

    subgraph Processing["Processing Layer"]
        CR[Container Runner]
        IPC[IPC Files]
    end

    subgraph Execution["Execution Layer"]
        Docker[Docker Container]
        Apple[Apple Container]
        Claude[Claude Code Agent]
    end

    subgraph Storage["Storage Layer"]
        GD[Groups Directory]
        SD[Store Directory]
        LD[Logs Directory]
    end

    WA -->|HTTP API| Main
    TG -->|Webhook/Polling| Main
    Main <-->|Read/Write| DB
    Main -->|Spawn| TS
    TS -->|Execute| CR
    Main -->|Handle Message| CR
    CR -->|Prepare| IPC
    CR -->|Mount| GD
    IPC --> CR
    CR -->|Launch| Docker
    CR -->|Launch| Apple
    Docker --> Claude
    Apple --> Claude
    Claude -->|Response| CR
    CR -->|Store| LD
    CR -->|Update| DB

Message Flow

sequenceDiagram
    actor User
    participant WhatsApp/Telegram
    participant NuClaw
    participant Database
    participant Container
    participant Claude

    User->>WhatsApp/Telegram: Send message (@Andy ...)
    WhatsApp/Telegram->>NuClaw: Webhook/Poll
    NuClaw->>NuClaw: Extract trigger (@Andy)
    NuClaw->>NuClaw: Check duplicate
    NuClaw->>Database: Store message
    NuClaw->>Database: Get group config
    NuClaw->>Container: Prepare IPC files
    NuClaw->>Container: Launch container
    Container->>Claude: Execute prompt
    Claude-->>Container: Return result
    Container-->>NuClaw: Parse output
    NuClaw->>Database: Store response
    NuClaw->>WhatsApp/Telegram: Send response
    WhatsApp/Telegram->>User: Display response

Scheduled Task Flow

sequenceDiagram
    participant Scheduler
    participant Database
    participant Container
    participant Claude
    participant WhatsApp/Telegram

    loop Every poll interval
        Scheduler->>Database: Query due tasks
        Database-->>Scheduler: Return tasks
        
        alt Task is due
            Scheduler->>Container: Execute task
            Container->>Claude: Run prompt
            Claude-->>Container: Return result
            Container-->>Scheduler: Task output
            Scheduler->>Database: Update task status
            Scheduler->>Database: Log run
            Scheduler->>WhatsApp/Telegram: Send result (optional)
        end
        
        Scheduler->>Scheduler: Calculate next run
        Scheduler->>Database: Update next_run
    end

Core Components

src/main.rs - Application entry point
src/whatsapp.rs - WhatsApp connection (via MCP)
src/telegram.rs - Telegram Bot API connection
src/container_runner.rs - Container management
src/task_scheduler.rs - Scheduled task execution
src/db.rs - SQLite database operations
src/config.rs - Configuration management

Requirements

Rust 1.70+
Docker or Apple Container
Node.js (for agent execution)
Claude Code subscription

One-Click Installation

Linux/macOS

# Run the deployment script
curl -sSL https://raw.githubusercontent.com/gyc567/nuclaw/main/deploy.sh | bash

Local Installation

# Clone and run deployment
git clone https://github.com/gyc567/nuclaw.git
cd nuclaw
chmod +x deploy.sh
./deploy.sh

The script will:

Detect your operating system
Install Rust/Cargo if needed
Install system dependencies (sqlite3)
Build the project in release mode
Run all tests
Verify installation

Manual Installation

# Build from source
git clone https://github.com/gyc567/nuclaw.git
cd nuclaw

# Create directories
mkdir -p store data groups logs

# Build
cargo build --release

# Verify
./target/release/nuclaw --help

Quick Start

# Build
cargo build --release

# Run with WhatsApp authentication
cargo run -- auth

# Start the service
cargo run

Configuration

Core Environment Variables

Variable	Default	Description
`ASSISTANT_NAME`	Andy	Trigger word for mentions
`CONTAINER_TIMEOUT`	300000	Agent execution timeout (ms)
`TZ`	UTC	Timezone for scheduled tasks
`CONTAINER_IMAGE`	anthropic/claude-code:latest	Docker image

WhatsApp Configuration

Variable	Description
`WHATSAPP_MCP_URL`	WhatsApp MCP Server URL (required)

Telegram Configuration

Variable	Default	Description
`TELEGRAM_BOT_TOKEN`	-	BotFather token (required)
`TELEGRAM_WEBHOOK_URL`	-	Webhook URL (optional)
`TELEGRAM_WEBHOOK_PATH`	telegram-webhook	Webhook path
`TELEGRAM_DM_POLICY`	pairing	DM policy: pairing/allowlist/open/disabled
`TELEGRAM_GROUP_POLICY`	allowlist	Group policy: open/allowlist/disabled
`TELEGRAM_TEXT_CHUNK_LIMIT`	4000	Max text chunk size
`TELEGRAM_WHITELIST_GROUPS`	-	Comma-separated group IDs

Mount Allowlist

Additional mounts are configured in ~/.config/nuclaw/mount-allowlist.json:

{
  "allowedRoots": [
    {
      "path": "~/projects",
      "allowReadWrite": true,
      "description": "Development projects"
    }
  ],
  "blockedPatterns": ["password", "secret"],
  "nonMainReadOnly": true
}

Telegram Setup

Step 1: Create a Bot

Open Telegram and search for @BotFather
Send /newbot to create a new bot
Follow the instructions to get your bot token

Step 2: Configure Environment

export TELEGRAM_BOT_TOKEN=your_bot_token_here
export TELEGRAM_WEBHOOK_URL=https://your-domain.com  # Optional, for webhook mode

Step 3: Run the Bot

# Run with Telegram mode
./target/release/nuclaw --telegram

DM Policy Options

pairing - Users must use a pairing code (default)
allowlist - Only whitelisted users can interact
open - Anyone can interact
disabled - Disable DM entirely

Group Policy Options

open - Any group can use the bot
allowlist - Only whitelisted groups can use the bot
disabled - Disable group functionality

WhatsApp Setup

# Configure WhatsApp MCP Server URL
export WHATSAPP_MCP_URL=http://localhost:3000

# Run authentication flow
./target/release/nuclaw --auth

# Start WhatsApp bot
./target/release/nuclaw --whatsapp

Development

# Run with debug logging
LOG_LEVEL=debug cargo run

# Run tests
cargo test

# Check code
cargo clippy

Project Structure

nuclaw/
├── src/              # Source code
├── docs/             # Documentation and reports
│   ├── TEST_REPORT.md
│   ├── DEPLOY_TEST_REPORT.md
│   └── plans/        # Roadmap and plans
├── store/            # Database storage
├── data/             # Application data
├── groups/           # Group contexts
└── logs/             # Container logs

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Roadmap

See ROADMAP.md for upcoming features and plans.

Documentation

Test Report - Detailed test results
Deployment Test Report - Deployment verification

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
Dockerfile.agent		Dockerfile.agent
README.md		README.md
README_CN.md		README_CN.md
ROADMAP.md		ROADMAP.md
TEST_REPORT.md		TEST_REPORT.md
deploy.sh		deploy.sh
install.ps1		install.ps1
install.sh		install.sh
tarpaulin-report.html		tarpaulin-report.html
train.py		train.py
uninstall.sh		uninstall.sh

Folders and files

Latest commit

History

Repository files navigation

NuClaw - Personal Claude Assistant

Why Rust?

Features

Architecture

System Architecture

Message Flow

Scheduled Task Flow

Core Components

Requirements

One-Click Installation

Linux/macOS

Local Installation

Manual Installation

Quick Start

Configuration

Core Environment Variables

WhatsApp Configuration

Telegram Configuration

Mount Allowlist

Telegram Setup

Step 1: Create a Bot

Step 2: Configure Environment

Step 3: Run the Bot

DM Policy Options

Group Policy Options

WhatsApp Setup

Development

Project Structure

Contributing

Roadmap

Documentation

License

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages