@rozek/nanoclaw 0.0.1

package/.claude/skills/add-ollama-tool/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: add-ollama-tool
+description: Add Ollama MCP server so the container agent can call local models for cheaper/faster tasks like summarization, translation, or general queries.
+---
+
+# Add Ollama Integration
+
+This skill adds a stdio-based MCP server that exposes local Ollama models as tools for the container agent. Claude remains the orchestrator but can offload work to local models.
+
+Tools added:
+- `ollama_list_models` — lists installed Ollama models
+- `ollama_generate` — sends a prompt to a specified model and returns the response
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `container/agent-runner/src/ollama-mcp-stdio.ts` exists. If it does, skip to Phase 3 (Configure).
+
+### Check prerequisites
+
+Verify Ollama is installed and running on the host:
+
+```bash
+ollama list
+```
+
+If Ollama is not installed, direct the user to https://ollama.com/download.
+
+If no models are installed, suggest pulling one:
+
+> You need at least one model. I recommend:
+>
+> ```bash
+> ollama pull gemma3:1b    # Small, fast (1GB)
+> ollama pull llama3.2     # Good general purpose (2GB)
+> ollama pull qwen3-coder:30b  # Best for code tasks (18GB)
+> ```
+
+## 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/ollama-tool
+git merge upstream/skill/ollama-tool
+```
+
+This merges in:
+- `container/agent-runner/src/ollama-mcp-stdio.ts` (Ollama MCP server)
+- `scripts/ollama-watch.sh` (macOS notification watcher)
+- Ollama MCP config in `container/agent-runner/src/index.ts` (allowedTools + mcpServers)
+- `[OLLAMA]` log surfacing in `src/container-runner.ts`
+- `OLLAMA_HOST` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Copy to per-group agent-runner
+
+Existing groups have a cached copy of the agent-runner source. Copy the new files:
+
+```bash
+for dir in data/sessions/*/agent-runner-src; do
+  cp container/agent-runner/src/ollama-mcp-stdio.ts "$dir/"
+  cp container/agent-runner/src/index.ts "$dir/"
+done
+```
+
+### Validate code changes
+
+```bash
+npm run build
+./container/build.sh
+```
+
+Build must be clean before proceeding.
+
+## Phase 3: Configure
+
+### Set Ollama host (optional)
+
+By default, the MCP server connects to `http://host.docker.internal:11434` (Docker Desktop) with a fallback to `localhost`. To use a custom Ollama host, add to `.env`:
+
+```bash
+OLLAMA_HOST=http://your-ollama-host:11434
+```
+
+### Restart the service
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 4: Verify
+
+### Test via WhatsApp
+
+Tell the user:
+
+> Send a message like: "use ollama to tell me the capital of France"
+>
+> The agent should use `ollama_list_models` to find available models, then `ollama_generate` to get a response.
+
+### Monitor activity (optional)
+
+Run the watcher script for macOS notifications when Ollama is used:
+
+```bash
+./scripts/ollama-watch.sh
+```
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log | grep -i ollama
+```
+
+Look for:
+- `Agent output: ... Ollama ...` — agent used Ollama successfully
+- `[OLLAMA] >>> Generating` — generation started (if log surfacing works)
+- `[OLLAMA] <<< Done` — generation completed
+
+## Troubleshooting
+
+### Agent says "Ollama is not installed"
+
+The agent is trying to run `ollama` CLI inside the container instead of using the MCP tools. This means:
+1. The MCP server wasn't registered — check `container/agent-runner/src/index.ts` has the `ollama` entry in `mcpServers`
+2. The per-group source wasn't updated — re-copy files (see Phase 2)
+3. The container wasn't rebuilt — run `./container/build.sh`
+
+### "Failed to connect to Ollama"
+
+1. Verify Ollama is running: `ollama list`
+2. Check Docker can reach the host: `docker run --rm curlimages/curl curl -s http://host.docker.internal:11434/api/tags`
+3. If using a custom host, check `OLLAMA_HOST` in `.env`
+
+### Agent doesn't use Ollama tools
+
+The agent may not know about the tools. Try being explicit: "use the ollama_generate tool with gemma3:1b to answer: ..."

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

@@ -0,0 +1,290 @@
+# Add Parallel AI Integration
+
+Adds Parallel AI MCP integration to NanoClaw for advanced web research capabilities.
+
+## What This Adds
+
+- **Quick Search** - Fast web lookups using Parallel Search API (free to use)
+- **Deep Research** - Comprehensive analysis using Parallel Task API (asks permission)
+- **Non-blocking Design** - Uses NanoClaw scheduler for result polling (no container blocking)
+
+## Prerequisites
+
+User must have:
+1. Parallel AI API key from https://platform.parallel.ai
+2. NanoClaw already set up and running
+3. Docker installed and running
+
+## Implementation Steps
+
+Run all steps automatically. Only pause for user input when explicitly needed.
+
+### 1. Get Parallel AI API Key
+
+Use `AskUserQuestion: Do you have a Parallel AI API key, or should I help you get one?`
+
+**If they have one:**
+Collect it now.
+
+**If they need one:**
+Tell them:
+> 1. Go to https://platform.parallel.ai
+> 2. Sign up or log in
+> 3. Navigate to API Keys section
+> 4. Create a new API key
+> 5. Copy the key and paste it here
+
+Wait for the API key.
+
+### 2. Add API Key to Environment
+
+Add `PARALLEL_API_KEY` to `.env`:
+
+```bash
+# Check if .env exists, create if not
+if [ ! -f .env ]; then
+    touch .env
+fi
+
+# Add PARALLEL_API_KEY if not already present
+if ! grep -q "PARALLEL_API_KEY=" .env; then
+    echo "PARALLEL_API_KEY=${API_KEY_FROM_USER}" >> .env
+    echo "✓ Added PARALLEL_API_KEY to .env"
+else
+    # Update existing key
+    sed -i.bak "s/^PARALLEL_API_KEY=.*/PARALLEL_API_KEY=${API_KEY_FROM_USER}/" .env
+    echo "✓ Updated PARALLEL_API_KEY in .env"
+fi
+```
+
+Verify:
+```bash
+grep "PARALLEL_API_KEY" .env | head -c 50
+```
+
+### 3. Update Container Runner
+
+Add `PARALLEL_API_KEY` to allowed environment variables in `src/container-runner.ts`:
+
+Find the line:
+```typescript
+const allowedVars = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];
+```
+
+Replace with:
+```typescript
+const allowedVars = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY', 'PARALLEL_API_KEY'];
+```
+
+### 4. Configure MCP Servers in Agent Runner
+
+Update `container/agent-runner/src/index.ts`:
+
+Find the section where `mcpServers` is configured (around line 237-252):
+```typescript
+const mcpServers: Record<string, any> = {
+  nanoclaw: ipcMcp
+};
+```
+
+Add Parallel AI MCP servers after the nanoclaw server:
+```typescript
+const mcpServers: Record<string, any> = {
+  nanoclaw: ipcMcp
+};
+
+// Add Parallel AI MCP servers if API key is available
+const parallelApiKey = process.env.PARALLEL_API_KEY;
+if (parallelApiKey) {
+  mcpServers['parallel-search'] = {
+    type: 'http',  // REQUIRED: Must specify type for HTTP MCP servers
+    url: 'https://search-mcp.parallel.ai/mcp',
+    headers: {
+      'Authorization': `Bearer ${parallelApiKey}`
+    }
+  };
+  mcpServers['parallel-task'] = {
+    type: 'http',  // REQUIRED: Must specify type for HTTP MCP servers  
+    url: 'https://task-mcp.parallel.ai/mcp',
+    headers: {
+      'Authorization': `Bearer ${parallelApiKey}`
+    }
+  };
+  log('Parallel AI MCP servers configured');
+} else {
+  log('PARALLEL_API_KEY not set, skipping Parallel AI integration');
+}
+```
+
+Also update the `allowedTools` array to include Parallel MCP tools (around line 242-248):
+```typescript
+allowedTools: [
+  'Bash',
+  'Read', 'Write', 'Edit', 'Glob', 'Grep',
+  'WebSearch', 'WebFetch',
+  'mcp__nanoclaw__*',
+  'mcp__parallel-search__*',
+  'mcp__parallel-task__*'
+],
+```
+
+### 5. Add Usage Instructions to CLAUDE.md
+
+Add Parallel AI usage instructions to `groups/main/CLAUDE.md`:
+
+Find the "## What You Can Do" section and add after the existing bullet points:
+```markdown
+- Use Parallel AI for web research and deep learning tasks
+```
+
+Then add a new section after "## What You Can Do":
+```markdown
+## Web Research Tools
+
+You have access to two Parallel AI research tools:
+
+### Quick Web Search (`mcp__parallel-search__search`)
+**When to use:** Freely use for factual lookups, current events, definitions, recent information, or verifying facts.
+
+**Examples:**
+- "Who invented the transistor?"
+- "What's the latest news about quantum computing?"
+- "When was the UN founded?"
+- "What are the top programming languages in 2026?"
+
+**Speed:** Fast (2-5 seconds)
+**Cost:** Low
+**Permission:** Not needed - use whenever it helps answer the question
+
+### Deep Research (`mcp__parallel-task__create_task_run`)
+**When to use:** Comprehensive analysis, learning about complex topics, comparing concepts, historical overviews, or structured research.
+
+**Examples:**
+- "Explain the development of quantum mechanics from 1900-1930"
+- "Compare the literary styles of Hemingway and Faulkner"
+- "Research the evolution of jazz from bebop to fusion"
+- "Analyze the causes of the French Revolution"
+
+**Speed:** Slower (1-20 minutes depending on depth)
+**Cost:** Higher (varies by processor tier)
+**Permission:** ALWAYS use `AskUserQuestion` before using this tool
+
+**How to ask permission:**
+```
+AskUserQuestion: I can do deep research on [topic] using Parallel's Task API. This will take 2-5 minutes and provide comprehensive analysis with citations. Should I proceed?
+```
+
+**After permission - DO NOT BLOCK! Use scheduler instead:**
+
+1. Create the task using `mcp__parallel-task__create_task_run`
+2. Get the `run_id` from the response
+3. Create a polling scheduled task using `mcp__nanoclaw__schedule_task`:
+   ```
+   Prompt: "Check Parallel AI task run [run_id] and send results when ready.
+
+   1. Use the Parallel Task MCP to check the task status
+   2. If status is 'completed', extract the results
+   3. Send results to user with mcp__nanoclaw__send_message
+   4. Use mcp__nanoclaw__complete_scheduled_task to mark this task as done
+
+   If status is still 'running' or 'pending', do nothing (task will run again in 30s).
+   If status is 'failed', send error message and complete the task."
+
+   Schedule: interval every 30 seconds
+   Context mode: isolated
+   ```
+4. Send acknowledgment with tracking link
+5. Exit immediately - scheduler handles the rest
+
+### Choosing Between Them
+
+**Use Search when:**
+- Question needs a quick fact or recent information
+- Simple definition or clarification
+- Verifying specific details
+- Current events or news
+
+**Use Deep Research (with permission) when:**
+- User wants to learn about a complex topic
+- Question requires analysis or comparison
+- Historical context or evolution of concepts
+- Structured, comprehensive understanding needed
+- User explicitly asks to "research" or "explain in depth"
+
+**Default behavior:** Prefer search for most questions. Only suggest deep research when the topic genuinely requires comprehensive analysis.
+```
+
+### 6. Rebuild Container
+
+Build the container with updated agent runner:
+
+```bash
+./container/build.sh
+```
+
+Verify the build:
+```bash
+echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "Container OK"
+```
+
+### 7. Restart Service
+
+Rebuild the main app and restart:
+
+```bash
+npm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+Wait 3 seconds for service to start, then verify:
+```bash
+sleep 3
+launchctl list | grep nanoclaw  # macOS
+# Linux: systemctl --user status nanoclaw
+```
+
+### 8. Test Integration
+
+Tell the user to test:
+> Send a message to your assistant: `@[YourAssistantName] what's the latest news about AI?`
+>
+> The assistant should use Parallel Search API to find current information.
+>
+> Then try: `@[YourAssistantName] can you research the history of artificial intelligence?`
+>
+> The assistant should ask for permission before using the Task API.
+
+Check logs to verify MCP servers loaded:
+```bash
+tail -20 logs/nanoclaw.log
+```
+
+Look for: `Parallel AI MCP servers configured`
+
+## Troubleshooting
+
+**Container hangs or times out:**
+- Check that `type: 'http'` is specified in MCP server config
+- Verify API key is correct in .env
+- Check container logs: `cat groups/main/logs/container-*.log | tail -50`
+
+**MCP servers not loading:**
+- Ensure PARALLEL_API_KEY is in .env
+- Verify container-runner.ts includes PARALLEL_API_KEY in allowedVars
+- Check agent-runner logs for "Parallel AI MCP servers configured" message
+
+**Task polling not working:**
+- Verify scheduled task was created: `sqlite3 store/messages.db "SELECT * FROM scheduled_tasks"`
+- Check task runs: `tail -f logs/nanoclaw.log | grep "scheduled task"`
+- Ensure task prompt includes proper Parallel MCP tool names
+
+## Uninstalling
+
+To remove Parallel AI integration:
+
+1. Remove from .env: `sed -i.bak '/PARALLEL_API_KEY/d' .env`
+2. Revert changes to container-runner.ts and agent-runner/src/index.ts
+3. Remove Web Research Tools section from groups/main/CLAUDE.md
+4. Rebuild: `./container/build.sh && npm run build`
+5. Restart: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)

package/.claude/skills/add-pdf-reader/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: add-pdf-reader
+description: Add PDF reading to NanoClaw agents. Extracts text from PDFs via pdftotext CLI. Handles WhatsApp attachments, URLs, and local files.
+---
+
+# Add PDF Reader
+
+Adds PDF reading capability to all container agents using poppler-utils (pdftotext/pdfinfo). PDFs sent as WhatsApp attachments are auto-downloaded to the group workspace.
+
+## Phase 1: Pre-flight
+
+1. Check if `container/skills/pdf-reader/pdf-reader` exists — skip to Phase 3 if already applied
+2. Confirm WhatsApp is installed first (`skill/whatsapp` merged). This skill modifies WhatsApp channel files.
+
+## Phase 2: Apply Code Changes
+
+### Ensure WhatsApp fork 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 skill/pdf-reader
+git merge whatsapp/skill/pdf-reader || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `container/skills/pdf-reader/SKILL.md` (agent-facing documentation)
+- `container/skills/pdf-reader/pdf-reader` (CLI script)
+- `poppler-utils` in `container/Dockerfile`
+- PDF attachment download in `src/channels/whatsapp.ts`
+- PDF tests in `src/channels/whatsapp.test.ts`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate
+
+```bash
+npm run build
+npx vitest run src/channels/whatsapp.test.ts
+```
+
+### Rebuild container
+
+```bash
+./container/build.sh
+```
+
+### Restart service
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 3: Verify
+
+### Test PDF extraction
+
+Send a PDF file in any registered WhatsApp chat. The agent should:
+1. Download the PDF to `attachments/`
+2. Respond acknowledging the PDF
+3. Be able to extract text when asked
+
+### Test URL fetching
+
+Ask the agent to read a PDF from a URL. It should use `pdf-reader fetch <url>`.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log | grep -i pdf
+```
+
+Look for:
+- `Downloaded PDF attachment` — successful download
+- `Failed to download PDF attachment` — media download issue
+
+## Troubleshooting
+
+### Agent says pdf-reader command not found
+
+Container needs rebuilding. Run `./container/build.sh` and restart the service.
+
+### PDF text extraction is empty
+
+The PDF may be scanned (image-based). pdftotext only handles text-based PDFs. Consider using the agent-browser to open the PDF visually instead.
+
+### WhatsApp PDF not detected
+
+Verify the message has `documentMessage` with `mimetype: application/pdf`. Some file-sharing apps send PDFs as generic files without the correct mimetype.

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

@@ -0,0 +1,117 @@
+---
+name: add-reactions
+description: Add WhatsApp emoji reaction support — receive, send, store, and search reactions.
+---
+
+# Add Reactions
+
+This skill adds emoji reaction support to NanoClaw's WhatsApp channel: receive and store reactions, send reactions from the container agent via MCP tool, and query reaction history from SQLite.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/status-tracker.ts` exists:
+
+```bash
+test -f src/status-tracker.ts && echo "Already applied" || echo "Not applied"
+```
+
+If already applied, skip to Phase 3 (Verify).
+
+## Phase 2: Apply Code Changes
+
+### Ensure WhatsApp fork 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 skill/reactions
+git merge whatsapp/skill/reactions || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This adds:
+- `scripts/migrate-reactions.ts` (database migration for `reactions` table with composite PK and indexes)
+- `src/status-tracker.ts` (forward-only emoji state machine for message lifecycle signaling, with persistence and retry)
+- `src/status-tracker.test.ts` (unit tests for StatusTracker)
+- `container/skills/reactions/SKILL.md` (agent-facing documentation for the `react_to_message` MCP tool)
+- Reaction support in `src/db.ts`, `src/channels/whatsapp.ts`, `src/types.ts`, `src/ipc.ts`, `src/index.ts`, `src/group-queue.ts`, and `container/agent-runner/src/ipc-mcp-stdio.ts`
+
+### Run database migration
+
+```bash
+npx tsx scripts/migrate-reactions.ts
+```
+
+### Validate code changes
+
+```bash
+npm test
+npm run build
+```
+
+All tests must pass and build must be clean before proceeding.
+
+## Phase 3: Verify
+
+### Build and restart
+
+```bash
+npm run build
+```
+
+Linux:
+```bash
+systemctl --user restart nanoclaw
+```
+
+macOS:
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+```
+
+### Test receiving reactions
+
+1. Send a message from your phone
+2. React to it with an emoji on WhatsApp
+3. Check the database:
+
+```bash
+sqlite3 store/messages.db "SELECT * FROM reactions ORDER BY timestamp DESC LIMIT 5;"
+```
+
+### Test sending reactions
+
+Ask the agent to react to a message via the `react_to_message` MCP tool. Check your phone — the reaction should appear on the message.
+
+## Troubleshooting
+
+### Reactions not appearing in database
+
+- Check NanoClaw logs for `Failed to process reaction` errors
+- Verify the chat is registered
+- Confirm the service is running
+
+### Migration fails
+
+- Ensure `store/messages.db` exists and is accessible
+- If "table reactions already exists", the migration already ran — skip it
+
+### Agent can't send reactions
+
+- Check IPC logs for `Unauthorized IPC reaction attempt blocked` — the agent can only react in its own group's chat
+- Verify WhatsApp is connected: check logs for connection status