NanoClaw: A Personal Claude Assistant Built for Understanding and Security

NanoClaw is a personal Claude assistant that runs securely in Apple containers, designed as a lightweight alternative to OpenClaw with a focus on transparency and customization. The project addresses a fundamental concern: running complex software with access to personal data without understanding how it works.

The Problem with Complexity

OpenClaw represents an impressive vision with 52+ modules, 8 config management files, 45+ dependencies, and abstractions for 15 channel providers. However, this complexity creates security concerns. Everything runs in one Node process with shared memory, relying on application-level security (allowlists, pairing codes) rather than OS isolation.

NanoClaw takes a radically different approach: one process, a handful of files, and agents running in actual Linux containers with filesystem isolation.

Core Philosophy

Small enough to understand. The entire codebase can be grasped in 8 minutes. No microservices, no message queues, no abstraction layers. Have Claude Code walk you through it.

Secure by isolation. Agents run in Linux containers (Apple Container) and can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your Mac.

Built for one user. This isn't a framework—it's working software that fits exact needs. You fork it and have Claude Code make it match your exact needs.

Skills over features. Contributors shouldn't add features (like Telegram support) to the codebase. Instead, they contribute skills like /add-telegram that transform your fork. You end up with clean code that does exactly what you need.

What You Get

NanoClaw provides WhatsApp I/O with message capabilities from your phone, isolated group context where each group has its own CLAUDE.md memory and runs in its own container sandbox, a main channel for admin control, scheduled tasks that run Claude and can message you back, web access for search and content fetching, and container isolation with optional integrations like Gmail via skills.

Usage

Talk to your assistant with the trigger word (default: @Andy):

• @Andy send an overview of the sales pipeline every weekday morning at 9am
• @Andy review the git history for the past week each Friday and update the README if there's drift
• @Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing

From the main channel, you can manage groups and tasks:

• @Andy list all scheduled tasks across groups
• @Andy pause the Monday briefing task
• @Andy join the Family Chat group

Customization

There are no configuration files to learn. Just tell Claude Code what you want:

• "Change the trigger word to @Bob"
• "Remember in the future to make responses shorter and more direct"
• "Add a custom greeting when I say good morning"
• "Store conversation summaries weekly"

Or run /customize for guided changes. The codebase is small enough that Claude can safely modify it.

Contributing

The project has a unique contribution model: don't add features, add skills. If you want to add Telegram support, don't create a PR that adds Telegram alongside WhatsApp. Instead, contribute a skill file (.claude/skills/add-telegram/SKILL.md) that teaches Claude Code how to transform a NanoClaw installation to use Telegram.

Users then run /add-telegram on their fork and get clean code that does exactly what they need, not a bloated system trying to support every use case.

Technical Architecture

NanoClaw uses WhatsApp (baileys) → SQLite → Polling loop → Container (Claude Agent SDK) → Response. It's a single Node.js process where agents execute in isolated Linux containers with mounted directories. IPC happens via filesystem. No daemons, no queues, no complexity.

Key files include:

• src/index.ts - Main app: WhatsApp connection, routing, IPC
• src/container-runner.ts - Spawns agent containers
• src/task-scheduler.ts - Runs scheduled tasks
• src/db.ts - SQLite operations
• groups/*/CLAUDE.md - Per-group memory

Requirements

• macOS Tahoe (26) or later - runs great on Mac Mini
• Node.js 20+
• Claude Code
• Apple Container Architecture

Security Model

Agents run in containers, not behind application-level permission checks. They can only access explicitly mounted directories. The codebase is small enough that you can actually review what you're running. See docs/SECURITY.md for the full security model.

Why This Matters

The project represents a philosophical stance in the AI assistant space: prioritize understanding and control over feature completeness. By making the codebase small enough to comprehend and secure through container isolation rather than complex permission systems, NanoClaw offers a different value proposition than feature-rich alternatives.

It's built for users who want AI assistance without surrendering control to systems they can't understand or audit. The skill-based contribution model ensures the core remains minimal while allowing extensive customization through AI-guided modifications.

NanoClaw demonstrates that in the age of AI assistants, sometimes the most valuable feature is the ability to understand exactly what your software is doing with your data.

GitHub Repository