Skip to main content
NanoClaw provides the core functionality of complex AI assistants, but in a codebase small enough to understand: one process and a handful of files. Claude agents run in their own Linux containers with filesystem isolation, not merely behind permission checks.

Quick start

Get NanoClaw running in minutes with Claude Code handling setup

Installation

Detailed installation instructions for macOS, Linux, and Windows (WSL2)

Security

Learn about container isolation and security boundaries

Architecture

Understand how NanoClaw works under the hood

​
Key features

​
Container isolation

Agents run in Linux containers (Apple Container on macOS, or Docker) with true filesystem isolation. They can only see what’s explicitly mounted. 
Channel (WA/TG/DC/Slack/Gmail) → SQLite → Polling loop → Container (Claude Agent SDK) → Response

​
Multi-messenger support

Message NanoClaw from any connected platform:
  • WhatsApp (via /add-whatsapp)
  • Telegram (via /add-telegram)
  • Discord (via /add-discord)
  • Slack (via /add-slack)
  • Gmail (via /add-gmail)
All channels are installed via skills — pick the ones you need during /setup.

​
Isolated group context

Each group has its own:
  • CLAUDE.md memory file
  • Isolated filesystem
  • Separate container sandbox with only that filesystem mounted

​
Agent swarms

NanoClaw is the first personal AI assistant to support Agent Swarms. Spin up teams of agents that collaborate in your chat.

​
Scheduled tasks

Set up recurring jobs that run Claude and message you back: 
@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 and message me a briefing

​
Philosophy

Small enough to understand

One process, a few source files and no microservices. Ask Claude Code to walk you through the entire codebase.

Secure by isolation

Agents run in Linux containers and can only see what’s explicitly mounted. Bash access is safe because commands run inside the container, not on your host.

Built for the individual user

NanoClaw isn’t a monolithic framework; it’s software that fits each user’s exact needs. Make your own fork and have Claude Code modify it to match your needs.

Customization = code changes

No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it’s safe to make changes.

AI-native

No installation wizard; Claude Code guides setup. No monitoring dashboard; ask Claude what’s happening. No debugging tools; describe the problem and Claude fixes it.

Skills over features

Instead of adding features to the codebase, contributors submit Claude Code skills like /add-telegram that transform your fork. You end up with clean code that does exactly what you need.

​
Core architecture

NanoClaw is built with simplicity in mind:
  • Single Node.js process - No microservices or complex orchestration
  • SQLite database - Per-group message queue with concurrency control
  • Container runtime - Apple Container (macOS) or Docker (macOS/Linux)
  • Claude Agent SDK - Runs Claude Code directly in containers
  • IPC via filesystem - Simple, reliable inter-process communication
Codebase size: ~39.8k tokens (20% of Claude’s context window). Small enough to understand completely.

​
Key source files

FilePurpose
src/index.tsOrchestrator: state, message loop, agent invocation
src/channels/*.tsChannel adapters (WhatsApp, Telegram, etc.)
src/ipc.tsIPC watcher and task processing
src/router.tsMessage formatting and outbound routing
src/group-queue.tsPer-group queue with global concurrency limit
src/container-runner.tsSpawns streaming agent containers
src/task-scheduler.tsRuns scheduled tasks
src/remote-control.tsRemote Control session management
src/db.tsSQLite operations (messages, groups, sessions, state)
groups/*/CLAUDE.mdPer-group memory

​
Community

Questions? Ideas? Join the Discord. NanoClaw is MIT licensed and available on GitHub.
Last modified on March 24, 2026