@rozek/nanoclaw 1.2.17

package/docs/DEBUG_CHECKLIST.md

@@ -0,0 +1,143 @@
+# NanoClaw Debug Checklist
+
+## Known Issues (2026-02-08)
+
+### 1. [FIXED] Resume branches from stale tree position
+When agent teams spawns subagent CLI processes, they write to the same session JSONL. On subsequent `query()` resumes, the CLI reads the JSONL but may pick a stale branch tip (from before the subagent activity), causing the agent's response to land on a branch the host never receives a `result` for. **Fix**: pass `resumeSessionAt` with the last assistant message UUID to explicitly anchor each resume.
+
+### 2. IDLE_TIMEOUT == CONTAINER_TIMEOUT (both 30 min)
+Both timers fire at the same time, so containers always exit via hard SIGKILL (code 137) instead of graceful `_close` sentinel shutdown. The idle timeout should be shorter (e.g., 5 min) so containers wind down between messages, while container timeout stays at 30 min as a safety net for stuck agents.
+
+### 3. Cursor advanced before agent succeeds
+`processGroupMessages` advances `lastAgentTimestamp` before the agent runs. If the container times out, retries find no messages (cursor already past them). Messages are permanently lost on timeout.
+
+## Quick Status Check
+
+```bash
+# 1. Is the service running?
+launchctl list | grep nanoclaw
+# Expected: PID  0  com.nanoclaw (PID = running, "-" = not running, non-zero exit = crashed)
+
+# 2. Any running containers?
+container ls --format '{{.Names}} {{.Status}}' 2>/dev/null | grep nanoclaw
+
+# 3. Any stopped/orphaned containers?
+container ls -a --format '{{.Names}} {{.Status}}' 2>/dev/null | grep nanoclaw
+
+# 4. Recent errors in service log?
+grep -E 'ERROR|WARN' logs/nanoclaw.log | tail -20
+
+# 5. Is WhatsApp connected? (look for last connection event)
+grep -E 'Connected to WhatsApp|Connection closed|connection.*close' logs/nanoclaw.log | tail -5
+
+# 6. Are groups loaded?
+grep 'groupCount' logs/nanoclaw.log | tail -3
+```
+
+## Session Transcript Branching
+
+```bash
+# Check for concurrent CLI processes in session debug logs
+ls -la data/sessions/<group>/.claude/debug/
+
+# Count unique SDK processes that handled messages
+# Each .txt file = one CLI subprocess. Multiple = concurrent queries.
+
+# Check parentUuid branching in transcript
+python3 -c "
+import json, sys
+lines = open('data/sessions/<group>/.claude/projects/-workspace-group/<session>.jsonl').read().strip().split('\n')
+for i, line in enumerate(lines):
+  try:
+    d = json.loads(line)
+    if d.get('type') == 'user' and d.get('message'):
+      parent = d.get('parentUuid', 'ROOT')[:8]
+      content = str(d['message'].get('content', ''))[:60]
+      print(f'L{i+1} parent={parent} {content}')
+  except: pass
+"
+```
+
+## Container Timeout Investigation
+
+```bash
+# Check for recent timeouts
+grep -E 'Container timeout|timed out' logs/nanoclaw.log | tail -10
+
+# Check container log files for the timed-out container
+ls -lt groups/*/logs/container-*.log | head -10
+
+# Read the most recent container log (replace path)
+cat groups/<group>/logs/container-<timestamp>.log
+
+# Check if retries were scheduled and what happened
+grep -E 'Scheduling retry|retry|Max retries' logs/nanoclaw.log | tail -10
+```
+
+## Agent Not Responding
+
+```bash
+# Check if messages are being received from WhatsApp
+grep 'New messages' logs/nanoclaw.log | tail -10
+
+# Check if messages are being processed (container spawned)
+grep -E 'Processing messages|Spawning container' logs/nanoclaw.log | tail -10
+
+# Check if messages are being piped to active container
+grep -E 'Piped messages|sendMessage' logs/nanoclaw.log | tail -10
+
+# Check the queue state — any active containers?
+grep -E 'Starting container|Container active|concurrency limit' logs/nanoclaw.log | tail -10
+
+# Check lastAgentTimestamp vs latest message timestamp
+sqlite3 store/messages.db "SELECT chat_jid, MAX(timestamp) as latest FROM messages GROUP BY chat_jid ORDER BY latest DESC LIMIT 5;"
+```
+
+## Container Mount Issues
+
+```bash
+# Check mount validation logs (shows on container spawn)
+grep -E 'Mount validated|Mount.*REJECTED|mount' logs/nanoclaw.log | tail -10
+
+# Verify the mount allowlist is readable
+cat ~/.config/nanoclaw/mount-allowlist.json
+
+# Check group's container_config in DB
+sqlite3 store/messages.db "SELECT name, container_config FROM registered_groups;"
+
+# Test-run a container to check mounts (dry run)
+# Replace <group-folder> with the group's folder name
+container run -i --rm --entrypoint ls nanoclaw-agent:latest /workspace/extra/
+```
+
+## WhatsApp Auth Issues
+
+```bash
+# Check if QR code was requested (means auth expired)
+grep 'QR\|authentication required\|qr' logs/nanoclaw.log | tail -5
+
+# Check auth files exist
+ls -la store/auth/
+
+# Re-authenticate if needed
+npm run auth
+```
+
+## Service Management
+
+```bash
+# Restart the service
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+
+# View live logs
+tail -f logs/nanoclaw.log
+
+# Stop the service (careful — running containers are detached, not killed)
+launchctl bootout gui/$(id -u)/com.nanoclaw
+
+# Start the service
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.nanoclaw.plist
+
+# Rebuild after code changes
+npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+```

package/docs/REQUIREMENTS.md

@@ -0,0 +1,196 @@
+# NanoClaw Requirements
+
+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. 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 uses Docker by default (cross-platform). For macOS users who prefer Apple Container:
+- `/convert-to-apple-container` - Switch from Docker to Apple Container (macOS-only)
+
+### Platform Support
+- `/setup-linux` - Make the full setup work on Linux (depends on Docker conversion)
+- `/setup-windows` - Windows support via WSL2 + Docker
+
+---
+
+## Vision
+
+A personal Claude assistant accessible via WhatsApp, with minimal custom code.
+
+**Core components:**
+- **Claude Agent SDK** as the core agent
+- **Containers** for isolated agent execution (Linux VMs)
+- **WhatsApp** as the primary I/O channel
+- **Persistent memory** per conversation and globally
+- **Scheduled tasks** that run Claude and can message back
+- **Web access** for search and browsing
+- **Browser automation** via agent-browser
+
+**Implementation approach:**
+- Use existing tools (WhatsApp connector, Claude Agent SDK, MCP servers)
+- Minimal glue code
+- File-based systems where possible (CLAUDE.md for memory, folders for groups)
+
+---
+
+## Architecture Decisions
+
+### Message Routing
+- A router listens to WhatsApp and routes messages based on configuration
+- Only messages from registered groups are processed
+- Trigger: `@Andy` prefix (case insensitive), configurable via `ASSISTANT_NAME` env var
+- Unregistered groups are ignored completely
+
+### Memory System
+- **Per-group memory**: Each group has a folder with its own `CLAUDE.md`
+- **Global memory**: Root `CLAUDE.md` is read by all groups, but only writable from "main" (self-chat)
+- **Files**: Groups can create/read files in their folder and reference them
+- Agent runs in the group's folder, automatically inherits both CLAUDE.md files
+
+### Session Management
+- Each group maintains a conversation session (via Claude Agent SDK)
+- Sessions auto-compact when context gets too long, preserving critical information
+
+### Container Isolation
+- All agents run inside containers (lightweight Linux VMs)
+- Each agent invocation spawns a container with mounted directories
+- Containers provide filesystem isolation - agents can only see mounted paths
+- Bash access is safe because commands run inside the container, not on the host
+- Browser automation via agent-browser with Chromium in the container
+
+### Scheduled Tasks
+- Users can ask Claude to schedule recurring or one-time tasks from any group
+- Tasks run as full agents in the context of the group that created them
+- Tasks have access to all tools including Bash (safe in container)
+- Tasks can optionally send messages to their group via `send_message` tool, or complete silently
+- Task runs are logged to the database with duration and result
+- Schedule types: cron expressions, intervals (ms), or one-time (ISO timestamp)
+- From main: can schedule tasks for any group, view/manage all tasks
+- From other groups: can only manage that group's tasks
+
+### Group Management
+- New groups are added explicitly via the main channel
+- Groups are registered in SQLite (via the main channel or IPC `register_group` command)
+- Each group gets a dedicated folder under `groups/`
+- Groups can have additional directories mounted via `containerConfig`
+
+### Main Channel Privileges
+- Main channel is the admin/control group (typically self-chat)
+- Can write to global memory (`groups/CLAUDE.md`)
+- Can schedule tasks for any group
+- Can view and manage tasks from all groups
+- Can configure additional directory mounts for any group
+
+---
+
+## Integration Points
+
+### WhatsApp
+- Using baileys library for WhatsApp Web connection
+- Messages stored in SQLite, polled by router
+- QR code authentication during setup
+
+### Scheduler
+- Built-in scheduler runs on the host, spawns containers for task execution
+- Custom `nanoclaw` MCP server (inside container) provides scheduling tools
+- Tools: `schedule_task`, `list_tasks`, `pause_task`, `resume_task`, `cancel_task`, `send_message`
+- Tasks stored in SQLite with run history
+- Scheduler loop checks for due tasks every minute
+- Tasks execute Claude Agent SDK in containerized group context
+
+### Web Access
+- Built-in WebSearch and WebFetch tools
+- Standard Claude Agent SDK capabilities
+
+### Browser Automation
+- agent-browser CLI with Chromium in container
+- Snapshot-based interaction with element references (@e1, @e2, etc.)
+- Screenshots, PDFs, video recording
+- Authentication state persistence
+
+---
+
+## Setup & Customization
+
+### Philosophy
+- Minimal configuration files
+- Setup and customization done via Claude Code
+- Users clone the repo and run Claude Code to configure
+- Each user gets a custom setup matching their exact needs
+
+### Skills
+- `/setup` - Install dependencies, authenticate WhatsApp, configure scheduler, start services
+- `/customize` - General-purpose skill for adding capabilities (new channels like Telegram, new integrations, behavior changes)
+- `/update` - Pull upstream changes, merge with customizations, run migrations
+
+### Deployment
+- Runs on local Mac via launchd
+- Single Node.js process handles everything
+
+---
+
+## Personal Configuration (Reference)
+
+These are the creator's settings, stored here for reference:
+
+- **Trigger**: `@Andy` (case insensitive)
+- **Response prefix**: `Andy:`
+- **Persona**: Default Claude (no custom personality)
+- **Main channel**: Self-chat (messaging yourself in WhatsApp)
+
+---
+
+## Project Name
+
+**NanoClaw** - A reference to Clawdbot (now OpenClaw).