NanoClaw

NanoClaw: Lightweighted Openclaw alternative, Reimagined for Simplicity and Security

NanoClaw is a groundbreaking personal AI assistant designed to bring the power of Claude directly to your workflow, with a strong emphasis on simplicity, security, and user understanding. Unlike complex, multi-module AI frameworks, NanoClaw offers a streamlined, single-process architecture that allows you to grasp its entire functionality in minutes. This transparency is key to its philosophy: empowering users to truly understand and customize their AI tools.

The Problem with Existing Solutions

The inspiration behind NanoClaw stems from a critical observation of existing AI frameworks like OpenClaw. While powerful, these frameworks often suffer from significant complexity. OpenClaw, for instance, boasts over 52 modules, 8 configuration management files, 45+ dependencies, and support for 15 different channel providers. This complexity introduces several challenges:

• Security Concerns: The security model relies heavily on application-level checks (allowlists, pairing codes) rather than robust OS-level isolation. This means a single process with shared memory could potentially expose sensitive user data.
• Lack of Transparency: The sheer volume of code and dependencies makes it difficult for users to fully understand how the system operates, hindering trust and customization.
• Maintenance Overhead: Managing numerous modules and dependencies can be a daunting task, especially for individual users.

NanoClaw's Philosophy: Simplicity, Security, and Customization

NanoClaw directly addresses these issues by adhering to a core set of principles:

• Small Enough to Understand: The entire codebase is designed to be comprehended quickly. With a single Node.js process and a handful of source files, users can gain a deep understanding of its inner workings.
• Secure by Isolation: NanoClaw leverages containerization for its agents. On macOS, it utilizes Apple Container, and on other systems (or as an alternative on macOS), it supports Docker. This provides true OS-level isolation, ensuring that agents can only access explicitly mounted directories, thereby enhancing security and privacy.
• Built for One User: NanoClaw is not a generic framework; it's a working piece of software tailored to specific needs. The intention is for users to fork the repository and then use Claude Code to adapt it to their unique requirements.
• Customization Through Code: Instead of complex configuration files, customization is achieved through direct code modification. The small codebase makes this a safe and manageable process.
• AI-Native Experience: NanoClaw embraces an AI-native approach. Setup is guided by Claude Code, operational status is queried by asking Claude, and debugging is handled by describing problems to Claude for resolution. This eliminates the need for traditional installation wizards, dashboards, or debugging tools.
• Skills Over Features: The project encourages contributions in the form of "skills" rather than direct feature additions to the core codebase. Skills are essentially instructions for Claude Code on how to transform a NanoClaw installation. This allows users to add support for new communication channels (like Telegram or Slack) or functionalities without bloating the core system, maintaining its simplicity and understandability.
• Best Harness, Best Model: By utilizing the Claude Agent SDK natively, NanoClaw ensures that the powerful Claude models are harnessed effectively. The project emphasizes the importance of a good "harness" – the framework that interacts with the AI model – to unlock its full potential.
• No ToS Gray Areas: The native use of the Claude Agent SDK with a user's own subscription and authentication token ensures legitimate usage, minimizing the risk of terms-of-service violations.

Key Features and Functionality

NanoClaw provides a robust set of features designed for personal AI assistance:

• WhatsApp Integration: Seamlessly integrates with WhatsApp via the baileys library, allowing Claude to send and receive messages directly from your phone.
• Isolated Group Context: Each group or conversation can have its own dedicated memory (CLAUDE.md), isolated filesystem, and a dedicated container sandbox. This ensures that each interaction is contextually relevant and secure.
• Main Channel (Self-Chat): A dedicated channel for administrative control, allowing users to manage groups, tasks, and the overall system.
• Scheduled Tasks: The ability to schedule recurring tasks for Claude, such as daily briefings, weekly summaries, or regular data analysis, with notifications sent back to the user.
• Web Access: Integrated capabilities for Claude to search the web and fetch information, expanding its utility for research and information gathering.
• Containerization: Agents run within isolated Linux containers, providing a secure sandboxed environment. This is managed through Apple Container on macOS or Docker on other platforms.
• Extensible Skills: The contribution model focuses on "skills" that teach Claude Code how to modify the NanoClaw installation. This allows for the addition of new communication channels (Telegram, Slack, Discord), platform support (Windows via WSL2), session management features (like a /clear command for conversation compaction), and more, without altering the core codebase.
• AI-Native Interaction: All management and customization are done through natural language commands to Claude, making the system highly accessible and user-friendly.

Architecture Overview

The NanoClaw architecture is intentionally simple and efficient:

1. WhatsApp Connection: The system connects to WhatsApp using the baileys library.
2. IPC via Filesystem: Communication between the main Node.js process and the agent containers occurs through the filesystem, ensuring isolation and simplicity.
3. Agent Execution: Agents run as separate processes within isolated Linux containers.
4. Task Scheduling: A dedicated module handles the scheduling and execution of recurring tasks.
5. SQLite Database: Used for managing conversation history, group data, and task scheduling information.

Key files in the codebase include:

• src/index.ts: The main application file, handling WhatsApp connection, message routing, and inter-process communication (IPC).
• src/container-runner.ts: Manages the spawning and lifecycle of agent containers.
• src/task-scheduler.ts: Orchestrates the execution of scheduled tasks.
• src/db.ts: Handles all SQLite database operations.
• groups/*/CLAUDE.md: Stores per-group memory and context.

Contributing and Customization

NanoClaw actively encourages contributions through its "skills" system. Instead of directly modifying the core code for new features, contributors are expected to create skill files (e.g., .claude/skills/add-telegram/SKILL.md) that guide Claude Code in transforming an existing NanoClaw installation. This approach ensures that the base system remains lean and understandable, while allowing users to tailor the assistant to their specific needs.

Security fixes, bug fixes, and essential improvements to the base configuration are welcome as direct code contributions. However, any additions related to new capabilities, OS compatibility, hardware support, or enhancements should ideally be implemented as skills. This modular approach to customization is central to NanoClaw's design.

Frequently Asked Questions (FAQ)

• Why WhatsApp and not other messaging platforms? NanoClaw uses WhatsApp because it's the platform the author uses. The design encourages users to fork the repository and contribute skills to add support for other platforms like Telegram, Signal, or Slack.

• Why Apple Container over Docker? On macOS, Apple Container offers a lightweight and fast experience, especially on Apple Silicon. However, Docker is fully supported and can be selected during the /setup process. On Linux, Docker is the default.

• Can I run this on Linux? Yes, NanoClaw supports Linux. The /setup command automatically configures Docker for Linux environments. A skill (/convert-to-docker) also exists for converting existing macOS installations to use Docker.

• Is it secure? Security is a primary focus. Agents run in isolated containers, accessing only explicitly mounted directories. While the codebase is small enough for users to review, users are still encouraged to exercise caution and review the security model detailed in docs/SECURITY.md.

• Why no configuration files? The project avoids configuration sprawl. Customization is intended to be done through code changes, allowing users to tailor the system precisely to their needs. If users desire configuration files, they can contribute skills to add them.

• How do I debug issues? Users are encouraged to interact with Claude Code directly for debugging. Commands like /debug,