NanoClaw is a personal AI assistant built to run securely within Apple containers, aiming for a lightweight, transparent, and highly customizable alternative to more complex AI frameworks like OpenClaw. The project's core philosophy emphasizes understandability, security through OS-level isolation, a user-centric design, and an AI-native operational paradigm.

Core Philosophy and Design Principles:

1. Simplicity and Understandability: The system is designed to be minimal, comprising a single Node.js process, a few source files, and deliberately avoiding microservices, message queues, or extensive abstraction layers. This enables users to comprehend the entire codebase rapidly.
2. Security by Isolation: Agents execute within isolated Linux containers (utilizing Apple Container technology), ensuring strict filesystem isolation. These containers can only access directories explicitly mounted, preventing unauthorized data access. Commands, including Bash, are run inside the container sandbox, not directly on the host macOS system.
3. User-Centric Customization: NanoClaw is built as a complete, working solution tailored for a single user's needs, rather than a generic framework. Customization is achieved directly by modifying the small codebase, guided and assisted by Claude Code itself, rather than through configuration files.
4. AI-Native Operations: Setup, monitoring, debugging, and system modifications are all handled conversationally by Claude Code. For instance, instead of debugging tools, users describe problems to Claude, which then assists in resolution.
5. "Skills over Features" Contribution Model: New functionalities (e.g., support for new communication channels) are not directly integrated into the core codebase via pull requests. Instead, they are contributed as "skills"—executable Claude Code scripts that teach Claude how to transform a user's fork of NanoClaw. This approach keeps the core system minimal and allows users to selectively apply features without bloating their installation.
6. Optimal AI Harnessing: The system directly leverages the Claude Agent SDK, which is considered an effective "harness" for Claude models, maximizing their capabilities and ensuring legitimate use of the Claude API without violating terms of service.

Key Capabilities:
NanoClaw primarily functions as a WhatsApp-interfaced AI assistant. It supports:

• Bidirectional messaging via WhatsApp.
• Isolated group contexts: Each WhatsApp group maintains its own persistent memory (stored in CLAUDE.md files), operates with a dedicated, isolated filesystem, and runs within its own container sandbox.
• A "main channel" (self-chat) for administrative control over tasks and groups.
• Scheduled tasks, allowing Claude to perform recurring actions and send notifications.
• Web access for searching and fetching content.
• Extensible integrations (e.g., Gmail) via skills.

Technical Architecture and Core Methodology:
The architecture is characterized by its lean, single-process design and robust container-based isolation:

• Main Application (src/index.ts): This central Node.js application manages the WhatsApp connection (via baileys library), handles message routing, and orchestrates inter-process communication (IPC) with the agent containers.
• Data Persistence (src/db.ts): A SQLite database stores application state, routing information, and potentially message history.
• Container Spawning (src/container-runner.ts): This module is responsible for dynamically spawning isolated Linux containers using Apple Container technology. Each container provides a sandboxed environment for an AI agent instance. These containers are ephemeral and instantiated on demand for specific agent tasks or group interactions.
• Task Scheduling (src/task-scheduler.ts): This component manages recurring jobs, polling the system to trigger Claude agent executions at predefined times.
• Inter-Process Communication (IPC): IPC between the main Node.js process and the running agent containers occurs exclusively via the filesystem. This approach, while potentially slower than shared memory or network sockets, aligns with the philosophy of simplicity and explicit isolation, as containers only see what is explicitly mounted.
• Agent Execution Context: When a message or a scheduled task triggers an AI operation, the system identifies the relevant group context. A new container is launched for this context, with only the necessary files (e.g., the group's CLAUDE.md memory file and designated input/output directories) explicitly mounted into its filesystem. The Claude Agent SDK runs within this isolated container, processes the input, interacts with its mounted memory and tools (e.g., web access), and outputs its response back to the main Node.js application via the filesystem, which then relays it to WhatsApp.
• Skill Execution: The "skills" mechanism allows Claude Code to modify the base system. When a user invokes a skill (e.g., /add-telegram), Claude Code generates and executes code changes directly on the user's nanoclaw repository, transforming it to incorporate new functionality. This live code modification is feasible due to the codebase's small size and modularity.

The system requires macOS Tahoe (26) or later and Node.js 20+. It explicitly avoids Docker by default in favor of Apple Container for lightness and speed on macOS, though conversion to Docker is possible via a skill.