diff --git a/README.md b/README.md index ccc1938..2248556 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

- My personal Claude assistant that runs securely in containers. Lightweight and built to be understood and customized for your own needs. + An AI assistant that runs agents securely in their own containers. Lightweight, built to be easily understood and completely customized for your needs.

@@ -13,49 +13,54 @@ 34.9k tokens, 17% of context window

+Using Claude Code, NanoClaw can dynamically rewrite its code to customize its feature set for your needs. + **New:** First AI assistant to support [Agent Swarms](https://code.claude.com/docs/en/agent-teams). Spin up teams of agents that collaborate in your chat. -## Why I Built This +## Why I Built NanoClaw -[OpenClaw](https://github.com/openclaw/openclaw) is an impressive project with a great vision. But I can't sleep well running software I don't understand with access to my life. OpenClaw has 52+ modules, 8 config management files, 45+ dependencies, and abstractions for 15 channel providers. Security is application-level (allowlists, pairing codes) rather than OS isolation. Everything runs in one Node process with shared memory. +[OpenClaw](https://github.com/openclaw/openclaw) is an impressive project, but I wouldn't have been able to sleep if I had given complex software I didn't understand full access to my life. OpenClaw has nearly half a million lines of code, 53 config files, and 70+ dependencies. Its security is at the application level (allowlists, pairing codes) rather than true OS-level isolation. Everything runs in one Node process with shared memory. -NanoClaw gives you the same core functionality in a codebase you can understand in 8 minutes. One process. A handful of files. Agents run in actual Linux containers with filesystem isolation, not behind permission checks. +NanoClaw provides that same core functionality, 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 ```bash -git clone https://github.com/qwibitai/nanoclaw.git -cd nanoclaw +git clone https://github.com/qwibitai/NanoClaw.git +cd NanoClaw claude ``` -Then run `/setup`. Claude Code handles everything: dependencies, authentication, container setup, service configuration. +Then run `/setup`. Claude Code handles everything: dependencies, authentication, container setup and service configuration. ## Philosophy -**Small enough to understand.** One process, a few source files. No microservices, no message queues, no abstraction layers. Have Claude Code walk you through it. +**Small enough to understand.** One process, a few source files and no microservices. If you want to understand the full NanoClaw codebase, just ask Claude Code to walk you through it. -**Secure by isolation.** Agents run in Linux containers (Apple Container on macOS, or Docker). They can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host. +**Secure by isolation.** Agents run in Linux containers (Apple Container on macOS, or Docker) and they can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host. -**Built for one user.** This isn't a framework. It's working software that fits my exact needs. You fork it and have Claude Code make it match your exact needs. +**Built for the individual user.** NanoClaw isn't a monolithic framework; it's software that fits each user's exact needs. Instead of becoming bloatware, NanoClaw is designed to be bespoke. You 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 this is safe. +**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, Claude fixes it. +**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.** Contributors shouldn't add features (e.g. support for Telegram) to the codebase. Instead, they contribute [claude code skills](https://code.claude.com/docs/en/skills) like `/add-telegram` that transform your fork. You end up with clean code that does exactly what you need. +**Skills over features.** Instead of adding features (e.g. support for Telegram) to the codebase, contributors submit [claude code skills](https://code.claude.com/docs/en/skills) like `/add-telegram` that transform your fork. You end up with clean code that does exactly what you need. -**Best harness, best model.** This runs on Claude Agent SDK, which means you're running Claude Code directly. The harness matters. A bad harness makes even smart models seem dumb, a good harness gives them superpowers. Claude Code is (IMO) the best harness available. +**Best harness, best model.** NanoClaw runs on the Claude Agent SDK, which means you're running Claude Code directly. Claude Code is highly capable and its coding and problem-solving capabilities allow it to modify and expand NanoClaw and tailor it to each user. ## What It Supports -- **WhatsApp I/O** - Message Claude from your phone -- **Isolated group context** - Each group has its own `CLAUDE.md` memory, isolated filesystem, and runs in its own container sandbox with only that filesystem mounted -- **Main channel** - Your private channel (self-chat) for admin control; every other group is completely isolated +- **Messenger I/O** - Message NanoClaw from your phone. Supports WhatsApp, Telegram, Discord, Slack, Signal and headless operation. +- **Isolated group context** - Each group has its own `CLAUDE.md` memory, isolated filesystem, and runs in its own container sandbox with only that filesystem mounted to it. +- **Main channel** - Your private channel (self-chat) for admin control; every group is completely isolated - **Scheduled tasks** - Recurring jobs that run Claude and can message you back -- **Web access** - Search and fetch content -- **Container isolation** - Agents sandboxed in Apple Container (macOS) or Docker (macOS/Linux) -- **Agent Swarms** - Spin up teams of specialized agents that collaborate on complex tasks (first personal AI assistant to support this) +- **Web access** - Search and fetch content from the Web +- **Container isolation** - Agents are sandboxed in Apple Container (macOS) or Docker (macOS/Linux) +- **Agent Swarms** - Spin up teams of specialized agents that collaborate on complex tasks. NanoClaw is the first personal AI assistant to support agent swarms. - **Optional integrations** - Add Gmail (`/add-gmail`) and more via skills ## Usage @@ -77,7 +82,7 @@ From the main channel (your self-chat), you can manage groups and tasks: ## Customizing -There are no configuration files to learn. Just tell Claude Code what you want: +NanoClaw doesn't use configuration files. To make changes, just tell Claude Code what you want: - "Change the trigger word to @Bob" - "Remember in the future to make responses shorter and more direct" @@ -88,16 +93,6 @@ Or run `/customize` for guided changes. The codebase is small enough that Claude can safely modify it. -## Updating - -Pull the latest NanoClaw changes into your fork: - -```bash -claude -``` - -Then run `/update`. Claude Code fetches upstream, previews changes, merges with your customizations, runs migrations, and verifies the result. - ## Contributing **Don't add features. Add skills.** @@ -113,11 +108,8 @@ Skills we'd like to see: **Communication Channels** - `/add-slack` - Add Slack -**Platform Support** -- `/setup-windows` - Windows via WSL2 + Docker - **Session Management** -- `/add-clear` - Add a `/clear` command that compacts the conversation (summarizes context while preserving critical information in the same session). Requires figuring out how to trigger compaction programmatically via the Claude Agent SDK. +- `/clear` - Add a `/clear` command that compacts the conversation (summarizes context while preserving critical information in the same session). Requires figuring out how to trigger compaction programmatically via the Claude Agent SDK. ## Requirements @@ -132,7 +124,7 @@ Skills we'd like to see: WhatsApp (baileys) --> SQLite --> Polling loop --> Container (Claude Agent SDK) --> Response ``` -Single Node.js process. Agents execute in isolated Linux containers with mounted directories. Per-group message queue with concurrency control. IPC via filesystem. +Single Node.js process. Agents execute in isolated Linux containers with filesystem isolation. Only mounted directories are accessible. Per-group message queue with concurrency control. IPC via filesystem. Key files: - `src/index.ts` - Orchestrator: state, message loop, agent invocation @@ -147,13 +139,9 @@ Key files: ## FAQ -**Why WhatsApp and not Telegram/Signal/etc?** - -Because I use WhatsApp. Fork it and run a skill to change it. That's the whole point. - **Why Docker?** -Docker provides cross-platform support (macOS and Linux) and a mature ecosystem. On macOS, you can optionally switch to Apple Container via `/convert-to-apple-container` for a lighter-weight native runtime. +Docker provides cross-platform support (macOS, Linux and even Windows via WSL2) and a mature ecosystem. On macOS, you can optionally switch to Apple Container via `/convert-to-apple-container` for a lighter-weight native runtime. **Can I run this on Linux?** @@ -165,19 +153,19 @@ Agents run in containers, not behind application-level permission checks. They c **Why no configuration files?** -We don't want configuration sprawl. Every user should customize it to so that the code matches exactly what they want rather than configuring a generic system. If you like having config files, tell Claude to add them. +We don't want configuration sprawl. Every user should customize NanoClaw so that the code does exactly what they want, rather than configuring a generic system. If you prefer having config files, you can tell Claude to add them. **How do I debug issues?** -Ask Claude Code. "Why isn't the scheduler running?" "What's in the recent logs?" "Why did this message not get a response?" That's the AI-native approach. +Ask Claude Code. "Why isn't the scheduler running?" "What's in the recent logs?" "Why did this message not get a response?" That's the AI-native approach that underlies NanoClaw. **Why isn't the setup working for me?** -I don't know. Run `claude`, then run `/debug`. If claude finds an issue that is likely affecting other users, open a PR to modify the setup SKILL.md. +If you have issues, during setup, Claude will try to dynamically fix them. If that doesn't work, run `claude`, then run `/debug`. If Claude finds an issue that is likely affecting other users, open a PR to modify the setup SKILL.md. **What changes will be accepted into the codebase?** -Security fixes, bug fixes, and clear improvements to the base configuration. That's it. +Only security fixes, bug fixes, and clear improvements will be accepted to the base configuration. That's all. Everything else (new capabilities, OS compatibility, hardware support, enhancements) should be contributed as skills.