tanmay/Regolith
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite documentation with project philosophy and RFS

Browse Source 
- Add "Why This Exists" section contrasting with OpenClaw
- Document core philosophy: small, secure, AI-native, skills over features
- Add RFS (Request for Skills) for community contributions
- Rewrite README with proper structure, examples, and FAQ
- Emphasize Claude Agent SDK benefits and ToS compliance

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Gavriel
2026-02-01 12:47:40 +02:00
parent 1d4cf51917
commit dbf39a9484
2 changed files with 191 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
README.md
View File

@@ -1,70 +1,160 @@
# NanoClaw # NanoClaw
Personal Claude assistant via WhatsApp. A personal Claude assistant. Lightweight, secure, and built to be understood and customized for your own needs.
## Why This Exists
This is the anti-[OpenClaw](https://github.com/anthropics/openclaw). That project became a monstrosity - multiple processes, endless configuration, endless integrations, security nightmares with leaky permission systems. It's impossible for anyone to actually understand the whole thing.
NanoClaw gives you the same core functionality in a codebase you can read in an afternoon. One Node.js process. A handful of files. Agents run in actual containers, not behind leaky application-level permissions.
## Philosophy
**Small enough to understand.** One process, a few source files. No microservices, no message queues, no abstraction layers.
**Secure by isolation.** Agents run in Linux containers (Apple Container). They 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 for my needs - WhatsApp and Email. You fork it and make it yours.
**Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that this is safe.
**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.
**Skills over features.** Contributors don't add "Telegram alongside WhatsApp." They contribute 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 the best harness available. OpenClaw runs on Pi; this runs the real thing.
**No ToS gray areas.** Because it uses Claude Agent SDK natively with no hacks or workarounds, using your subscription with your auth token is completely legitimate. No risk of being shut down for terms of service violations (I am not a lawyer).
## Quick Start ## Quick Start
```bash ```bash
git clone https://github.com/yourname/nanoclaw.git git clone https://github.com/anthropics/nanoclaw.git
cd nanoclaw cd nanoclaw
claude claude
# Run: /setup
``` ```
Claude Code handles installation, authentication, and service setup. Then run `/setup`. Claude Code handles everything: dependencies, authentication, container setup, service configuration.
## Features That's it. No manual configuration files to edit.
- **WhatsApp I/O**: Message Claude from your phone ## What You Get
- **Persistent memory**: Per-group conversation context
- **Global memory**: Shared context across all groups - **WhatsApp I/O** - Message Claude from your phone
- **Email tools**: Read/send via Gmail (optional) - **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
- **Scheduled tasks**: Recurring reminders and jobs - **Main channel** - Your private channel (self-chat) for admin control; every other group is completely isolated
- **Web access**: Search and fetch content - **Email** - Read and send via Gmail (optional)
- **Scheduled tasks** - Recurring jobs that run Claude and can message you back
- **Web access** - Search and fetch content
- **Container isolation** - Agents sandboxed in Linux VMs
## Usage ## Usage
Talk to your assistant with the trigger word (default: `@Andy`):
```
@Andy give me an overview of the sales pipeline
@Andy review the git history for the past week and update CLAUDE.md with anything notable
@Andy research recent developments in AI agents and write a summary to research/ai-agents.md
@Andy every Monday at 8am, compile news from Hacker News and TechCrunch and message me a briefing
```
Clear conversation context:
``` ```
@Andy what's the weather in NYC?
@Andy summarize my unread emails
@Andy remind me every Monday at 9am to check metrics
/clear /clear
``` ```
From main channel: From the main channel (your self-chat), you can manage groups and tasks:
``` ```
@Andy add group "Family Chat" @Andy list all scheduled tasks across groups
@Andy list groups @Andy pause the Monday briefing task
```
## Requirements
- macOS (or Linux)
- Node.js 18+
- Claude Code CLI (authenticated)
## Manual Setup
```bash
npm install
npm run build
npm start
``` ```
## Customization ## Customization
Run Claude Code and ask to: There are no configuration files to learn. Just tell Claude Code what you want:
- "Change trigger to @Bot"
- "Make responses more concise"
Or use `/customize`. - "Change the trigger word to @Bot"
- "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. You're not configuring a black box - you're shaping code you can read.
## Contributing
**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.
### RFS (Request for Skills)
Skills we'd love to see:
**Communication Channels**
- `/add-telegram` - Add Telegram as input
- `/add-slack` - Add Slack as input
- `/add-discord` - Add Discord as input
- `/convert-to-telegram` - Replace WhatsApp entirely
**Container Runtime**
- `/convert-to-docker` - Replace Apple Container with Docker (unlocks Linux)
**Platform Support**
- `/setup-linux` - Full Linux support (depends on Docker)
- `/setup-windows` - Windows via WSL2 + Docker
## Requirements
- macOS Tahoe (26) or later - runs great on Mac Mini
- Node.js 20+
- [Claude Code](https://claude.ai/download)
- [Apple Container](https://github.com/apple/container)
## Architecture ## Architecture
Single Node.js process using: ```
- `@whiskeysockets/baileys` - WhatsApp Web API WhatsApp (baileys) --> SQLite --> Polling loop --> Container (Claude Agent SDK) --> Response
- `@anthropic-ai/claude-agent-sdk` - Claude Agent SDK ```
- `better-sqlite3` - Message storage
Single Node.js process. Agents execute in isolated Linux containers with mounted directories. IPC via filesystem. No daemons, no queues, no complexity.
Key files:
- `src/index.ts` - Main app: WhatsApp connection, routing, IPC
- `src/container-runner.ts` - Spawns agent containers
- `src/scheduler.ts` - Runs scheduled tasks
- `src/db.ts` - SQLite operations
- `groups/*/CLAUDE.md` - Per-group memory
## 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 Apple Container instead of Docker?**
Lightweight, fast, and built into macOS. Requires macOS Tahoe - runs great on a Mac Mini. Contribute a skill to convert to Docker if you want Docker.
**Can I run this on Linux?**
Yes. Run Claude Code and say "make this run on Linux." Half an hour of back-and-forth and it'll work. When you're done, ask Claude to create a skill explaining how to make it work on Linux, then contribute the skill back to the project.
**Is this secure?**
More secure than OpenClaw. Agents run in actual Linux VMs, not behind application-level permission checks. They can only access explicitly mounted directories. But you should still review what you're running - the codebase is small enough to read.
**Why no configuration files?**
We don't want configuration sprawl. It's a small codebase - make it match your exact needs. Every user should customize it to what they want rather than configuring a generic system. If you like having config files, 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.
## License ## License

63
REQUIREMENTS.md
View File

@@ -4,6 +4,67 @@ Original requirements and design decisions from the project creator.
--- ---
## Why This Exists
This is a lightweight, secure alternative to OpenClaw (formerly ClawBot). That project became a monstrosity - 4-5 different processes running different gateways, endless configuration files, endless integrations. It's a security nightmare where agents don't run in isolated processes; there's all kinds of leaky workarounds trying to prevent them from accessing parts of the system they shouldn't. It's impossible for anyone to realistically understand the whole codebase. When you run it you're kind of just yoloing it.
NanoClaw gives you the core functionality without that mess.
---
## Philosophy
### Small Enough to Understand
The entire codebase should be something you can read and understand. One Node.js process. A handful of source files. No microservices, no message queues, no abstraction layers.
### Security Through True Isolation
Instead of application-level permission systems trying to prevent agents from accessing things, agents run in actual Linux containers (Apple Container). The isolation is at the OS level. Agents 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 or a platform. It's working software for my specific needs. I use WhatsApp and Email, so it supports WhatsApp and Email. I don't use Telegram, so it doesn't support Telegram. I add the integrations I actually want, not every possible integration.
### Customization = Code Changes
No configuration sprawl. If you want different behavior, modify the code. The codebase is small enough that this is safe and practical. Very minimal things like the trigger word are in config. Everything else - just change the code to do what you want.
### AI-Native Development
I don't need an installation wizard - Claude Code guides the setup. I don't need a monitoring dashboard - I ask Claude Code what's happening. I don't need elaborate logging UIs - I ask Claude to read the logs. I don't need debugging tools - I describe the problem and Claude fixes it.
The codebase assumes you have an AI collaborator. It doesn't need to be excessively self-documenting or self-debugging because Claude is always there.
### Skills Over Features
When people contribute, they shouldn't add "Telegram support alongside WhatsApp." They should contribute a skill like `/add-telegram` that transforms the codebase. Users fork the repo, run skills to customize, and end up with clean code that does exactly what they need - not a bloated system trying to support everyone's use case simultaneously.
---
## RFS (Request for Skills)
Skills we'd love contributors to build:
### Communication Channels
Skills to add or switch to different messaging platforms:
- `/add-telegram` - Add Telegram as an input channel
- `/add-slack` - Add Slack as an input channel
- `/add-discord` - Add Discord as an input channel
- `/add-sms` - Add SMS via Twilio or similar
- `/convert-to-telegram` - Replace WhatsApp with Telegram entirely
### Container Runtime
The project currently uses Apple Container (macOS-only). We need:
- `/convert-to-docker` - Replace Apple Container with standard Docker
- This unlocks Linux support and broader deployment options
### Platform Support
- `/setup-linux` - Make the full setup work on Linux (depends on Docker conversion)
- `/setup-windows` - Windows support via WSL2 + Docker
---
## Vision ## Vision
A personal Claude assistant accessible via WhatsApp, with minimal custom code. A personal Claude assistant accessible via WhatsApp, with minimal custom code.
@@ -17,7 +78,7 @@ A personal Claude assistant accessible via WhatsApp, with minimal custom code.
- **Web access** for search and browsing - **Web access** for search and browsing
- **Browser automation** via agent-browser - **Browser automation** via agent-browser
**Design philosophy:** **Implementation approach:**
- Leverage existing tools (WhatsApp connector, Claude Agent SDK, MCP servers) - Leverage existing tools (WhatsApp connector, Claude Agent SDK, MCP servers)
- Minimal glue code - Minimal glue code
- File-based systems where possible (CLAUDE.md for memory, folders for groups) - File-based systems where possible (CLAUDE.md for memory, folders for groups)