You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: rewrite READMEs for pluggable multi-channel architecture
Reflects the architectural shift from a hardcoded WhatsApp bot to a
pluggable channel platform. Adds upgrading notice, Mermaid architecture
diagram, CI/License/TypeScript/PRs badges, and clarifies that slash
commands run inside the Claude Code CLI.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
An AI assistant that runs agents securely in their own containers. Lightweight, built to be easily understood and completely customized for your needs.
6
+
A pluggable AI assistant platform. Agents run in containers. Channels install as skills. Small enough to read, built to be yours.
Using Claude Code, NanoClaw can dynamically rewrite its code to customize its feature set for your needs.
17
-
18
-
**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.
22
+
NanoClaw ships as a minimal core with **no channels built in.** You add exactly the channels you need — WhatsApp, Telegram, Slack, Discord, Gmail — by running [skills](#skills-over-features) inside Claude Code. Each channel self-registers at startup; unconfigured channels are silently skipped. No feature flags, no config toggles — just clean code that does what you need.
19
23
20
-
## Why I Built NanoClaw
24
+
## Why
21
25
22
26
[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.
23
27
@@ -28,52 +32,76 @@ NanoClaw provides that same core functionality, but in a codebase small enough t
/add-whatsapp # or /add-telegram, /add-slack, /add-discord, /add-gmail
43
+
```
44
+
45
+
> **Note:** Commands prefixed with `/` are [Claude Code skills](https://code.claude.com/docs/en/skills). Type them inside the `claude` CLI prompt, not in your regular terminal.
46
+
47
+
You can run multiple channels simultaneously or use just one.
48
+
49
+
## Upgrading from Pre-Pluggable Versions
50
+
51
+
> **Breaking change.** WhatsApp is no longer bundled in the core — it's now a pluggable skill, just like every other channel. If you're upgrading an existing installation:
52
+
>
53
+
> ```bash
54
+
> claude # open Claude Code in your NanoClaw directory
55
+
>```
56
+
>```
57
+
> /add-whatsapp # re-installs WhatsApp as a pluggable channel
58
+
>```
59
+
>
60
+
> Your existing auth credentials, groups, and scheduled tasks are preserved. The skill just wires WhatsApp back into the new channel registry.
35
61
36
62
## Philosophy
37
63
38
-
**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.
64
+
<a id="skills-over-features"></a>
65
+
66
+
**Small enough to understand.** One process, a few source files, no microservices. Want to understand the full codebase? Ask Claude Code to walk you through it. The whole thing fits in a single context window.
39
67
40
-
**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.
68
+
**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 execute inside the container, not on your host.
41
69
42
-
**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.
70
+
**Built for the individual.** NanoClaw isn't a monolithic framework; it's software that fits each user's exact needs. Fork it, point Claude Code at it, and make it yours.
43
71
44
-
**Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it's safe to make changes.
72
+
**Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that this is safe.
45
73
46
74
**AI-native.**
47
-
- No installation wizard; Claude Code guides setup.
48
-
- No monitoring dashboard; ask Claude what's happening.
49
-
- No debugging tools; describe the problem and Claude fixes it.
75
+
- No installation wizard — Claude Code guides setup.
76
+
- No monitoring dashboard — ask Claude what's happening.
77
+
- No debugging tools — describe the problem and Claude fixes it.
50
78
51
-
**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.
79
+
**Skills over features.** This is the core design principle. Traditional platforms bolt on every channel behind feature flags and configuration layers. NanoClaw does the opposite: channels, integrations, and capabilities are [Claude Code skills](https://code.claude.com/docs/en/skills) that **mutate your fork.** Run `/add-telegram` and you get clean, auditable Telegram code committed to your codebase — not a 15-channel abstraction layer you'll never read.
52
80
53
-
**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.
81
+
**Best harness, best model.** NanoClaw runs on the Claude Agent SDK — you're running Claude Code directly. Its coding and problem-solving capabilities let it modify, expand, and tailor NanoClaw to each user.
54
82
55
83
## What It Supports
56
84
57
-
-**Messenger I/O**- Message NanoClaw from your phone. Supports WhatsApp, Telegram, Discord, Slack, Signal and headless operation.
58
-
-**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.
59
-
-**Main channel**- Your private channel (self-chat) for admin control; every group is completely isolated
60
-
-**Scheduled tasks**- Recurring jobs that run Claude and can message you back
61
-
-**Web access**- Search and fetch content from the Web
62
-
-**Container isolation**- Agents are sandboxed in Apple Container (macOS) or Docker (macOS/Linux)
63
-
-**Agent Swarms**- Spin up teams of specialized agents that collaborate on complex tasks. NanoClaw is the first personal AI assistant to support agent swarms.
64
-
-**Optional integrations**- Add Gmail (`/add-gmail`) and more via skills
85
+
- **Pluggable channels** — Add WhatsApp (`/add-whatsapp`), Telegram (`/add-telegram`), Slack (`/add-slack`), Discord (`/add-discord`), or Gmail (`/add-gmail`). Run one or many simultaneously.
86
+
- **Isolated group context** — Each group has its own `CLAUDE.md` memory, isolated filesystem, and runs in its own container sandbox.
87
+
- **Main channel** — Your private channel (self-chat) for admin control; every other group is fully isolated.
88
+
- **Scheduled tasks** — Recurring jobs that run Claude and can message you back.
89
+
- **Web access** — Search and fetch content from the web.
90
+
- **Container isolation** — Agents sandboxed in Apple Container (macOS) or Docker (macOS/Linux).
91
+
- **Agent Swarms** — Spin up teams of specialized agents that collaborate on complex tasks via [Agent Teams](https://code.claude.com/docs/en/agent-teams).
92
+
- **Zero-config channel discovery** — Channels auto-detect credentials at startup. If credentials exist, the channel connects. Nothing to toggle.
65
93
66
94
## Usage
67
95
68
-
Talk to your assistant with the trigger word (default: `@Andy`):
96
+
Talk to your assistant with the trigger word (default: `@Andy`) from any connected channel:
69
97
70
98
```
71
99
@Andy send an overview of the sales pipeline every weekday morning at 9am (has access to my Obsidian vault folder)
72
100
@Andy review the git history for the past week each Friday and update the README if there's drift
73
101
@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing
74
102
```
75
103
76
-
From the main channel (your self-chat), you can manage groups and tasks:
104
+
From the main channel (your self-chat), manage groups and tasks:
77
105
```
78
106
@Andy list all scheduled tasks across groups
79
107
@Andy pause the Monday briefing task
@@ -82,34 +110,37 @@ From the main channel (your self-chat), you can manage groups and tasks:
82
110
83
111
## Customizing
84
112
85
-
NanoClaw doesn't use configuration files. To make changes, just tell Claude Code what you want:
113
+
No configuration files. Tell Claude Code what you want:
86
114
87
115
- "Change the trigger word to @Bob"
88
-
- "Remember in the future to make responses shorter and more direct"
116
+
- "Make responses shorter and more direct"
89
117
- "Add a custom greeting when I say good morning"
90
118
- "Store conversation summaries weekly"
91
119
92
-
Or run `/customize` for guided changes.
120
+
Or run `/customize` inside Claude Code for guided changes.
93
121
94
122
The codebase is small enough that Claude can safely modify it.
95
123
96
124
## Contributing
97
125
98
126
**Don't add features. Add skills.**
99
127
100
-
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 installationto use Telegram.
128
+
Want to add a new channel or integration? Contribute a skill (`.claude/skills/add-<name>/`) that teaches Claude Code how to transform a NanoClaw installation. Users run the skill on their fork and get clean code that does exactly what they need — not a bloated system trying to support every use case simultaneously.
101
129
102
-
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.
130
+
See existing channel skills (`/add-whatsapp`, `/add-telegram`, `/add-slack`, `/add-discord`, `/add-gmail`) for the pattern.
103
131
104
132
### RFS (Request for Skills)
105
133
106
134
Skills we'd like to see:
107
135
108
136
**Communication Channels**
109
-
-`/add-slack` - Add Slack
137
+
- `/add-signal` — Add Signal as a channel
110
138
111
139
**Session Management**
112
-
-`/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.
140
+
- `/clear` — Compact the conversation (summarize context while preserving critical information in the same session). Requires figuring out how to trigger compaction programmatically via the Claude Agent SDK.
141
+
142
+
**Platform Support**
143
+
- `/setup-windows` — Windows support via WSL2 + Docker
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.
196
+
Single Node.js process. Channels are pluggable — each registers a factory function via `src/channels/registry.ts`, and the orchestrator instantiates whichever channels have credentials present. Agents execute in isolated Linux containers. Per-group message queue with concurrency control. IPC via filesystem.
Channels follow a self-registration pattern. Each channel skill adds a file to `src/channels/` that:
217
+
218
+
1. Implements the `Channel` interface (`connect`, `sendMessage`, `ownsJid`, `disconnect`, ...)
219
+
2. Calls `registerChannel(name, factory)` at module load
220
+
3. Returns `null` from the factory if credentials are missing
221
+
222
+
The barrel file `src/channels/index.ts` imports all channel modules, triggering registration. The orchestrator loops through registered channels and connects whichever ones return a valid instance. No if-else chains, no feature flags — just the factory pattern.
139
223
140
224
## FAQ
141
225
@@ -145,31 +229,31 @@ Docker provides cross-platform support (macOS, Linux and even Windows via WSL2)
145
229
146
230
**Can I run this on Linux?**
147
231
148
-
Yes. Docker is the default runtime and works on both macOS and Linux. Just run `/setup`.
232
+
Yes. Docker is the default runtime and works on both macOS and Linux. Run `/setup` inside Claude Code.
149
233
150
234
**Is this secure?**
151
235
152
236
Agents run in containers, not behind application-level permission checks. They can only access explicitly mounted directories. You should still review what you're running, but the codebase is small enough that you actually can. See [docs/SECURITY.md](docs/SECURITY.md) for the full security model.
153
237
238
+
**How do I add a channel?**
239
+
240
+
Run the corresponding skill inside Claude Code: `/add-whatsapp`, `/add-telegram`, `/add-slack`, `/add-discord`, or `/add-gmail`. Each skill installs the channel code, guides you through authentication, and registers it. You can run multiple channels at the same time.
241
+
154
242
**Why no configuration files?**
155
243
156
-
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.
244
+
We don't want configuration sprawl. Every user should customize NanoClaw so that the code does exactly what they need, rather than configuring a generic system. If you prefer config files, tell Claude to add them.
157
245
158
246
**How do I debug issues?**
159
247
160
-
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.
248
+
Ask Claude Code. "Why isn't the scheduler running?" "What's in the recent logs?" "Why did this message not get a response?" Or run `/debug` inside Claude Code for guided troubleshooting.
161
249
162
-
**Why isn't the setup working for me?**
250
+
**Why isn't setup working for me?**
163
251
164
-
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.
252
+
During setup, Claude will try to dynamically fix issues. If that doesn't work, run `/debug` inside Claude Code. If Claude finds an issue likely affecting other users, open a PR to modify the setup SKILL.md.
165
253
166
254
**What changes will be accepted into the codebase?**
167
255
168
-
Only security fixes, bug fixes, and clear improvements will be accepted to the base configuration. That's all.
169
-
170
-
Everything else (new capabilities, OS compatibility, hardware support, enhancements) should be contributed as skills.
171
-
172
-
This keeps the base system minimal and lets every user customize their installation without inheriting features they don't want.
256
+
Security fixes, bug fixes, and clear improvements to the core. Everything else — new channels, integrations, platform support — should be contributed as skills. This keeps the base system minimal and lets every user customize their installation without inheriting features they don't want.
0 commit comments