@rozek/nanoclaw 1.2.17

package/.claude/skills/add-whatsapp/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: add-whatsapp
+description: Add WhatsApp as a channel. Can replace other channels entirely or run alongside them. Uses QR code or pairing code for authentication.
+---
+
+# Add WhatsApp Channel
+
+This skill adds WhatsApp support to NanoClaw. It installs the WhatsApp channel code, dependencies, and guides through authentication, registration, and configuration.
+
+## Phase 1: Pre-flight
+
+### Check current state
+
+Check if WhatsApp is already configured. If `store/auth/` exists with credential files, skip to Phase 4 (Registration) or Phase 5 (Verify).
+
+```bash
+ls store/auth/creds.json 2>/dev/null && echo "WhatsApp auth exists" || echo "No WhatsApp auth"
+```
+
+### Detect environment
+
+Check whether the environment is headless (no display server):
+
+```bash
+[[ -z "$DISPLAY" && -z "$WAYLAND_DISPLAY" && "$OSTYPE" != darwin* ]] && echo "IS_HEADLESS=true" || echo "IS_HEADLESS=false"
+```
+
+### Ask the user
+
+Use `AskUserQuestion` to collect configuration. **Adapt auth options based on environment:**
+
+If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?
+- **Pairing code** (Recommended) - Enter a numeric code on your phone (no camera needed, requires phone number)
+- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
+
+Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to authenticate WhatsApp?
+- **QR code in browser** (Recommended) - Opens a browser window with a large, scannable QR code
+- **Pairing code** - Enter a numeric code on your phone (no camera needed, requires phone number)
+- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
+
+If they chose pairing code:
+
+AskUserQuestion: What is your phone number? (Include country code without +, e.g., 1234567890)
+
+## Phase 2: Apply Code Changes
+
+Check if `src/channels/whatsapp.ts` already exists. If it does, skip to Phase 3 (Authentication).
+
+### Ensure channel remote
+
+```bash
+git remote -v
+```
+
+If `whatsapp` is missing, add it:
+
+```bash
+git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch whatsapp main
+git merge whatsapp/main || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/whatsapp.ts` (WhatsAppChannel class with self-registration via `registerChannel`)
+- `src/channels/whatsapp.test.ts` (41 unit tests)
+- `src/whatsapp-auth.ts` (standalone WhatsApp authentication script)
+- `setup/whatsapp-auth.ts` (WhatsApp auth setup step)
+- `import './whatsapp.js'` appended to the channel barrel file `src/channels/index.ts`
+- `'whatsapp-auth'` step added to `setup/index.ts`
+- `@whiskeysockets/baileys`, `qrcode`, `qrcode-terminal` npm dependencies in `package.json`
+- `ASSISTANT_HAS_OWN_NUMBER` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate code changes
+
+```bash
+npm install
+npm run build
+npx vitest run src/channels/whatsapp.test.ts
+```
+
+All tests must pass and build must be clean before proceeding.
+
+## Phase 3: Authentication
+
+### Clean previous auth state (if re-authenticating)
+
+```bash
+rm -rf store/auth/
+```
+
+### Run WhatsApp authentication
+
+For QR code in browser (recommended):
+
+```bash
+npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+```
+
+(Bash timeout: 150000ms)
+
+Tell the user:
+
+> A browser window will open with a QR code.
+>
+> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
+> 2. Scan the QR code in the browser
+> 3. The page will show "Authenticated!" when done
+
+For QR code in terminal:
+
+```bash
+npx tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal
+```
+
+Tell the user to run `npm run auth` in another terminal, then:
+
+> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
+> 2. Scan the QR code displayed in the terminal
+
+For pairing code:
+
+Tell the user to have WhatsApp open on **Settings > Linked Devices > Link a Device**, ready to tap **"Link with phone number instead"** — the code expires in ~60 seconds and must be entered immediately.
+
+Run the auth process in the background and poll `store/pairing-code.txt` for the code:
+
+```bash
+rm -f store/pairing-code.txt && npx tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number> > /tmp/wa-auth.log 2>&1 &
+```
+
+Then immediately poll for the code (do NOT wait for the background command to finish):
+
+```bash
+for i in $(seq 1 20); do [ -f store/pairing-code.txt ] && cat store/pairing-code.txt && break; sleep 1; done
+```
+
+Display the code to the user the moment it appears. Tell them:
+
+> **Enter this code now** — it expires in ~60 seconds.
+>
+> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
+> 2. Tap **Link with phone number instead**
+> 3. Enter the code immediately
+
+After the user enters the code, poll for authentication to complete:
+
+```bash
+for i in $(seq 1 60); do grep -q 'AUTH_STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'AUTH_STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done
+```
+
+**If failed:** qr_timeout → re-run. logged_out → delete `store/auth/` and re-run. 515 → re-run. timeout → ask user, offer retry.
+
+### Verify authentication succeeded
+
+```bash
+test -f store/auth/creds.json && echo "Authentication successful" || echo "Authentication failed"
+```
+
+### Configure environment
+
+Channels auto-enable when their credentials are present — WhatsApp activates when `store/auth/creds.json` exists.
+
+Sync to container environment:
+
+```bash
+mkdir -p data/env && cp .env data/env/env
+```
+
+## Phase 4: Registration
+
+### Configure trigger and channel type
+
+Get the bot's WhatsApp number: `node -e "const c=require('./store/auth/creds.json');console.log(c.me.id.split(':')[0].split('@')[0])"`
+
+AskUserQuestion: Is this a shared phone number (personal WhatsApp) or a dedicated number (separate device)?
+- **Shared number** - Your personal WhatsApp number (recommended: use self-chat or a solo group)
+- **Dedicated number** - A separate phone/SIM for the assistant
+
+AskUserQuestion: What trigger word should activate the assistant?
+- **@Andy** - Default trigger
+- **@Claw** - Short and easy
+- **@Claude** - Match the AI name
+
+AskUserQuestion: What should the assistant call itself?
+- **Andy** - Default name
+- **Claw** - Short and easy
+- **Claude** - Match the AI name
+
+AskUserQuestion: Where do you want to chat with the assistant?
+
+**Shared number options:**
+- **Self-chat** (Recommended) - Chat in your own "Message Yourself" conversation
+- **Solo group** - A group with just you and the linked device
+- **Existing group** - An existing WhatsApp group
+
+**Dedicated number options:**
+- **DM with bot** (Recommended) - Direct message the bot's number
+- **Solo group** - A group with just you and the bot
+- **Existing group** - An existing WhatsApp group
+
+### Get the JID
+
+**Self-chat:** JID = your phone number with `@s.whatsapp.net`. Extract from auth credentials:
+
+```bash
+node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0]+'@s.whatsapp.net')"
+```
+
+**DM with bot:** Ask for the bot's phone number. JID = `NUMBER@s.whatsapp.net`
+
+**Group (solo, existing):** Run group sync and list available groups:
+
+```bash
+npx tsx setup/index.ts --step groups
+npx tsx setup/index.ts --step groups --list
+```
+
+The output shows `JID|GroupName` pairs. Present candidates as AskUserQuestion (names only, not JIDs).
+
+### Register the chat
+
+```bash
+npx tsx setup/index.ts --step register \
+  --jid "<jid>" \
+  --name "<chat-name>" \
+  --trigger "@<trigger>" \
+  --folder "whatsapp_main" \
+  --channel whatsapp \
+  --assistant-name "<name>" \
+  --is-main \
+  --no-trigger-required  # Only for main/self-chat
+```
+
+For additional groups (trigger-required):
+
+```bash
+npx tsx setup/index.ts --step register \
+  --jid "<group-jid>" \
+  --name "<group-name>" \
+  --trigger "@<trigger>" \
+  --folder "whatsapp_<group-name>" \
+  --channel whatsapp
+```
+
+## Phase 5: Verify
+
+### Build and restart
+
+```bash
+npm run build
+```
+
+Restart the service:
+
+```bash
+# macOS (launchd)
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+
+# Linux (systemd)
+systemctl --user restart nanoclaw
+
+# Linux (nohup fallback)
+bash start-nanoclaw.sh
+```
+
+### Test the connection
+
+Tell the user:
+
+> Send a message to your registered WhatsApp chat:
+> - For self-chat / main: Any message works
+> - For groups: Use the trigger word (e.g., "@Andy hello")
+>
+> The assistant should respond within a few seconds.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log
+```
+
+## Troubleshooting
+
+### QR code expired
+
+QR codes expire after ~60 seconds. Re-run the auth command:
+
+```bash
+rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts
+```
+
+### Pairing code not working
+
+Codes expire in ~60 seconds. To retry:
+
+```bash
+rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts --pairing-code --phone <phone>
+```
+
+Enter the code **immediately** when it appears. Also ensure:
+1. Phone number includes country code without `+` (e.g., `1234567890`)
+2. Phone has internet access
+3. WhatsApp is updated to the latest version
+
+If pairing code keeps failing, switch to QR-browser auth instead:
+
+```bash
+rm -rf store/auth/ && npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+```
+
+### "conflict" disconnection
+
+This happens when two instances connect with the same credentials. Ensure only one NanoClaw process is running:
+
+```bash
+pkill -f "node dist/index.js"
+# Then restart
+```
+
+### Bot not responding
+
+Check:
+1. Auth credentials exist: `ls store/auth/creds.json`
+3. Chat is registered: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE '%whatsapp%' OR jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"`
+4. Service is running: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux)
+5. Logs: `tail -50 logs/nanoclaw.log`
+
+### Group names not showing
+
+Run group metadata sync:
+
+```bash
+npx tsx setup/index.ts --step groups
+```
+
+This fetches all group names from WhatsApp. Runs automatically every 24 hours.
+
+## After Setup
+
+If running `npm run dev` while the service is active:
+
+```bash
+# macOS:
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+npm run dev
+# When done testing:
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+
+# Linux:
+# systemctl --user stop nanoclaw
+# npm run dev
+# systemctl --user start nanoclaw
+```
+
+## Removal
+
+To remove WhatsApp integration:
+
+1. Delete auth credentials: `rm -rf store/auth/`
+2. Remove WhatsApp registrations: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"`
+3. Sync env: `mkdir -p data/env && cp .env data/env/env`
+4. Rebuild and restart: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `npm run build && systemctl --user restart nanoclaw` (Linux)

package/.claude/skills/convert-to-apple-container/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: convert-to-apple-container
+description: Switch from Docker to Apple Container for macOS-native container isolation. Use when the user wants Apple Container instead of Docker, or is setting up on macOS and prefers the native runtime. Triggers on "apple container", "convert to apple container", "switch to apple container", or "use apple container".
+---
+
+# Convert to Apple Container
+
+This skill switches NanoClaw's container runtime from Docker to Apple Container (macOS-only). It uses the skills engine for deterministic code changes, then walks through verification.
+
+**What this changes:**
+- Container runtime binary: `docker` → `container`
+- Mount syntax: `-v path:path:ro` → `--mount type=bind,source=...,target=...,readonly`
+- Startup check: `docker info` → `container system status` (with auto-start)
+- Orphan detection: `docker ps --filter` → `container ls --format json`
+- Build script default: `docker` → `container`
+- Dockerfile entrypoint: `.env` shadowing via `mount --bind` inside the container (Apple Container only supports directory mounts, not file mounts like Docker's `/dev/null` overlay)
+- Container runner: main-group containers start as root for `mount --bind`, then drop privileges via `setpriv`
+
+**What stays the same:**
+- Mount security/allowlist validation
+- All exported interfaces and IPC protocol
+- Non-main container behavior (still uses `--user` flag)
+- All other functionality
+
+## Prerequisites
+
+Verify Apple Container is installed:
+
+```bash
+container --version && echo "Apple Container ready" || echo "Install Apple Container first"
+```
+
+If not installed:
+- Download from https://github.com/apple/container/releases
+- Install the `.pkg` file
+- Verify: `container --version`
+
+Apple Container requires macOS. It does not work on Linux.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+```bash
+grep "CONTAINER_RUNTIME_BIN" src/container-runtime.ts
+```
+
+If it already shows `'container'`, the runtime is already Apple Container. Skip to Phase 3.
+
+## Phase 2: Apply Code Changes
+
+### Ensure upstream remote
+
+```bash
+git remote -v
+```
+
+If `upstream` is missing, add it:
+
+```bash
+git remote add upstream https://github.com/qwibitai/nanoclaw.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch upstream skill/apple-container
+git merge upstream/skill/apple-container
+```
+
+This merges in:
+- `src/container-runtime.ts` — Apple Container implementation (replaces Docker)
+- `src/container-runtime.test.ts` — Apple Container-specific tests
+- `src/container-runner.ts` — .env shadow mount fix and privilege dropping
+- `container/Dockerfile` — entrypoint that shadows .env via `mount --bind`
+- `container/build.sh` — default runtime set to `container`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate code changes
+
+```bash
+npm test
+npm run build
+```
+
+All tests must pass and build must be clean before proceeding.
+
+## Phase 3: Verify
+
+### Ensure Apple Container runtime is running
+
+```bash
+container system status || container system start
+```
+
+### Build the container image
+
+```bash
+./container/build.sh
+```
+
+### Test basic execution
+
+```bash
+echo '{}' | container run -i --entrypoint /bin/echo nanoclaw-agent:latest "Container OK"
+```
+
+### Test readonly mounts
+
+```bash
+mkdir -p /tmp/test-ro && echo "test" > /tmp/test-ro/file.txt
+container run --rm --entrypoint /bin/bash \
+  --mount type=bind,source=/tmp/test-ro,target=/test,readonly \
+  nanoclaw-agent:latest \
+  -c "cat /test/file.txt && touch /test/new.txt 2>&1 || echo 'Write blocked (expected)'"
+rm -rf /tmp/test-ro
+```
+
+Expected: Read succeeds, write fails with "Read-only file system".
+
+### Test read-write mounts
+
+```bash
+mkdir -p /tmp/test-rw
+container run --rm --entrypoint /bin/bash \
+  -v /tmp/test-rw:/test \
+  nanoclaw-agent:latest \
+  -c "echo 'test write' > /test/new.txt && cat /test/new.txt"
+cat /tmp/test-rw/new.txt && rm -rf /tmp/test-rw
+```
+
+Expected: Both operations succeed.
+
+### Full integration test
+
+```bash
+npm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+```
+
+Send a message via WhatsApp and verify the agent responds.
+
+## Troubleshooting
+
+**Apple Container not found:**
+- Download from https://github.com/apple/container/releases
+- Install the `.pkg` file
+- Verify: `container --version`
+
+**Runtime won't start:**
+```bash
+container system start
+container system status
+```
+
+**Image build fails:**
+```bash
+# Clean rebuild — Apple Container caches aggressively
+container builder stop && container builder rm && container builder start
+./container/build.sh
+```
+
+**Container can't write to mounted directories:**
+Check directory permissions on the host. The container runs as uid 1000.
+
+## Summary of Changed Files
+
+| File | Type of Change |
+|------|----------------|
+| `src/container-runtime.ts` | Full replacement — Docker → Apple Container API |
+| `src/container-runtime.test.ts` | Full replacement — tests for Apple Container behavior |
+| `src/container-runner.ts` | .env shadow mount removed, main containers start as root with privilege drop |
+| `container/Dockerfile` | Entrypoint: `mount --bind` for .env shadowing, `setpriv` privilege drop |
+| `container/build.sh` | Default runtime: `docker` → `container` |

package/.claude/skills/customize/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: customize
+description: Add new capabilities or modify NanoClaw behavior. Use when user wants to add channels (Telegram, Slack, email input), change triggers, add integrations, modify the router, or make any other customizations. This is an interactive skill that asks questions to understand what the user wants.
+---
+
+# NanoClaw Customization
+
+This skill helps users add capabilities or modify behavior. Use AskUserQuestion to understand what they want before making changes.
+
+## Workflow
+
+1. **Understand the request** - Ask clarifying questions
+3. **Plan the changes** - Identify files to modify. If a skill exists for the request (e.g., `/add-telegram` for adding Telegram), invoke it instead of implementing manually.
+4. **Implement** - Make changes directly to the code
+5. **Test guidance** - Tell user how to verify
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Orchestrator: state, message loop, agent invocation |
+| `src/channels/whatsapp.ts` | WhatsApp connection, auth, send/receive |
+| `src/ipc.ts` | IPC watcher and task processing |
+| `src/router.ts` | Message formatting and outbound routing |
+| `src/types.ts` | TypeScript interfaces (includes Channel) |
+| `src/config.ts` | Assistant name, trigger pattern, directories |
+| `src/db.ts` | Database initialization and queries |
+| `src/whatsapp-auth.ts` | Standalone WhatsApp authentication script |
+| `groups/CLAUDE.md` | Global memory/persona |
+
+## Common Customization Patterns
+
+### Adding a New Input Channel (e.g., Telegram, Slack, Email)
+
+Questions to ask:
+- Which channel? (Telegram, Slack, Discord, email, SMS, etc.)
+- Same trigger word or different?
+- Same memory hierarchy or separate?
+- Should messages from this channel go to existing groups or new ones?
+
+Implementation pattern:
+1. Create `src/channels/{name}.ts` implementing the `Channel` interface from `src/types.ts` (see `src/channels/whatsapp.ts` for reference)
+2. Add the channel instance to `main()` in `src/index.ts` and wire callbacks (`onMessage`, `onChatMetadata`)
+3. Messages are stored via the `onMessage` callback; routing is automatic via `ownsJid()`
+
+### Adding a New MCP Integration
+
+Questions to ask:
+- What service? (Calendar, Notion, database, etc.)
+- What operations needed? (read, write, both)
+- Which groups should have access?
+
+Implementation:
+1. Add MCP server config to the container settings (see `src/container-runner.ts` for how MCP servers are mounted)
+2. Document available tools in `groups/CLAUDE.md`
+
+### Changing Assistant Behavior
+
+Questions to ask:
+- What aspect? (name, trigger, persona, response style)
+- Apply to all groups or specific ones?
+
+Simple changes → edit `src/config.ts`
+Persona changes → edit `groups/CLAUDE.md`
+Per-group behavior → edit specific group's `CLAUDE.md`
+
+### Adding New Commands
+
+Questions to ask:
+- What should the command do?
+- Available in all groups or main only?
+- Does it need new MCP tools?
+
+Implementation:
+1. Commands are handled by the agent naturally — add instructions to `groups/CLAUDE.md` or the group's `CLAUDE.md`
+2. For trigger-level routing changes, modify `processGroupMessages()` in `src/index.ts`
+
+### Changing Deployment
+
+Questions to ask:
+- Target platform? (Linux server, Docker, different Mac)
+- Service manager? (systemd, Docker, supervisord)
+
+Implementation:
+1. Create appropriate service files
+2. Update paths in config
+3. Provide setup instructions
+
+## After Changes
+
+Always tell the user:
+```bash
+# Rebuild and restart
+npm run build
+# macOS:
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+# Linux:
+# systemctl --user restart nanoclaw
+```
+
+## Example Interaction
+
+User: "Add Telegram as an input channel"
+
+1. Ask: "Should Telegram use the same @Andy trigger, or a different one?"
+2. Ask: "Should Telegram messages create separate conversation contexts, or share with WhatsApp groups?"
+3. Create `src/channels/telegram.ts` implementing the `Channel` interface (see `src/channels/whatsapp.ts`)
+4. Add the channel to `main()` in `src/index.ts`
+5. Tell user how to authenticate and test