Personal Claude assistant. See README.md for philosophy and setup. See docs/REQUIREMENTS.md for architecture decisions.
Single Node.js process with skill-based channel system. Channels (WhatsApp, Telegram, Slack, Discord, Gmail) are skills that self-register at startup. Messages route to Claude Agent SDK running in containers (Linux VMs). Each group has isolated filesystem and memory.
| File | Purpose |
|---|---|
src/index.ts |
Orchestrator: state, message loop, agent invocation |
src/channels/registry.ts |
Channel registry (self-registration at startup) |
src/ipc.ts |
IPC watcher and task processing |
src/router.ts |
Message formatting and outbound routing |
src/config.ts |
Trigger pattern, paths, intervals |
src/container-runner.ts |
Spawns agent containers with mounts |
src/task-scheduler.ts |
Runs scheduled tasks |
src/db.ts |
SQLite operations |
groups/{name}/CLAUDE.md |
Per-group memory (isolated) |
container/skills/agent-browser.md |
Browser automation tool (available to all agents via Bash) |
| Skill | When to Use |
|---|---|
/setup |
First-time installation, authentication, service configuration |
/customize |
Adding channels, integrations, changing behavior |
/debug |
Container issues, logs, troubleshooting |
/update-nanoclaw |
Bring upstream NanoClaw updates into a customized install |
/qodo-pr-resolver |
Fetch and fix Qodo PR review issues interactively or in batch |
/get-qodo-rules |
Load org- and repo-level coding rules from Qodo before code tasks |
Run commands directly—don't tell the user to run them.
npm run dev # Run with hot reload
npm run build # Compile TypeScript
./container/build.sh # Rebuild agent containerService management:
# macOS (launchd)
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # restart
# Linux (systemd)
systemctl --user start nanoclaw
systemctl --user stop nanoclaw
systemctl --user restart nanoclawWhatsApp not connecting after upgrade: WhatsApp is now a separate channel fork, not bundled in core. Run /add-whatsapp (or git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git && git fetch whatsapp main && (git merge whatsapp/main || { git checkout --theirs package-lock.json && git add package-lock.json && git merge --continue; }) && npm run build) to install it. Existing auth credentials and groups are preserved.
The container buildkit caches the build context aggressively. --no-cache alone does NOT invalidate COPY steps — the builder's volume retains stale files. To force a truly clean rebuild, prune the builder then re-run ./container/build.sh.