@rozek/nanoclaw 1.2.17

package/.claude/skills/debug/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: debug
+description: Debug container agent issues. Use when things aren't working, container fails, authentication problems, or to understand how the container system works. Covers logs, environment variables, mounts, and common issues.
+---
+
+# NanoClaw Container Debugging
+
+This guide covers debugging the containerized agent execution system.
+
+## Architecture Overview
+
+```
+Host (macOS)                          Container (Linux VM)
+─────────────────────────────────────────────────────────────
+src/container-runner.ts               container/agent-runner/
+    │                                      │
+    │ spawns container                      │ runs Claude Agent SDK
+    │ with volume mounts                   │ with MCP servers
+    │                                      │
+    ├── data/env/env ──────────────> /workspace/env-dir/env
+    ├── groups/{folder} ───────────> /workspace/group
+    ├── data/ipc/{folder} ────────> /workspace/ipc
+    ├── data/sessions/{folder}/.claude/ ──> /home/node/.claude/ (isolated per-group)
+    └── (main only) project root ──> /workspace/project
+```
+
+**Important:** The container runs as user `node` with `HOME=/home/node`. Session files must be mounted to `/home/node/.claude/` (not `/root/.claude/`) for session resumption to work.
+
+## Log Locations
+
+| Log | Location | Content |
+|-----|----------|---------|
+| **Main app logs** | `logs/nanoclaw.log` | Host-side WhatsApp, routing, container spawning |
+| **Main app errors** | `logs/nanoclaw.error.log` | Host-side errors |
+| **Container run logs** | `groups/{folder}/logs/container-*.log` | Per-run: input, mounts, stderr, stdout |
+| **Claude sessions** | `~/.claude/projects/` | Claude Code session history |
+
+## Enabling Debug Logging
+
+Set `LOG_LEVEL=debug` for verbose output:
+
+```bash
+# For development
+LOG_LEVEL=debug npm run dev
+
+# For launchd service (macOS), add to plist EnvironmentVariables:
+<key>LOG_LEVEL</key>
+<string>debug</string>
+# For systemd service (Linux), add to unit [Service] section:
+# Environment=LOG_LEVEL=debug
+```
+
+Debug level shows:
+- Full mount configurations
+- Container command arguments
+- Real-time container stderr
+
+## Common Issues
+
+### 1. "Claude Code process exited with code 1"
+
+**Check the container log file** in `groups/{folder}/logs/container-*.log`
+
+Common causes:
+
+#### Missing Authentication
+```
+Invalid API key · Please run /login
+```
+**Fix:** Ensure `.env` file exists with either OAuth token or API key:
+```bash
+cat .env  # Should show one of:
+# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...  (subscription)
+# ANTHROPIC_API_KEY=sk-ant-api03-...        (pay-per-use)
+```
+
+#### Root User Restriction
+```
+--dangerously-skip-permissions cannot be used with root/sudo privileges
+```
+**Fix:** Container must run as non-root user. Check Dockerfile has `USER node`.
+
+### 2. Environment Variables Not Passing
+
+**Runtime note:** Environment variables passed via `-e` may be lost when using `-i` (interactive/piped stdin).
+
+**Workaround:** The system extracts only authentication variables (`CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`) from `.env` and mounts them for sourcing inside the container. Other env vars are not exposed.
+
+To verify env vars are reaching the container:
+```bash
+echo '{}' | docker run -i \
+  -v $(pwd)/data/env:/workspace/env-dir:ro \
+  --entrypoint /bin/bash nanoclaw-agent:latest \
+  -c 'export $(cat /workspace/env-dir/env | xargs); echo "OAuth: ${#CLAUDE_CODE_OAUTH_TOKEN} chars, API: ${#ANTHROPIC_API_KEY} chars"'
+```
+
+### 3. Mount Issues
+
+**Container mount notes:**
+- Docker supports both `-v` and `--mount` syntax
+- Use `:ro` suffix for readonly mounts:
+  ```bash
+  # Readonly
+  -v /path:/container/path:ro
+
+  # Read-write
+  -v /path:/container/path
+  ```
+
+To check what's mounted inside a container:
+```bash
+docker run --rm --entrypoint /bin/bash nanoclaw-agent:latest -c 'ls -la /workspace/'
+```
+
+Expected structure:
+```
+/workspace/
+├── env-dir/env           # Environment file (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY)
+├── group/                # Current group folder (cwd)
+├── project/              # Project root (main channel only)
+├── global/               # Global CLAUDE.md (non-main only)
+├── ipc/                  # Inter-process communication
+│   ├── messages/         # Outgoing WhatsApp messages
+│   ├── tasks/            # Scheduled task commands
+│   ├── current_tasks.json    # Read-only: scheduled tasks visible to this group
+│   └── available_groups.json # Read-only: WhatsApp groups for activation (main only)
+└── extra/                # Additional custom mounts
+```
+
+### 4. Permission Issues
+
+The container runs as user `node` (uid 1000). Check ownership:
+```bash
+docker run --rm --entrypoint /bin/bash nanoclaw-agent:latest -c '
+  whoami
+  ls -la /workspace/
+  ls -la /app/
+'
+```
+
+All of `/workspace/` and `/app/` should be owned by `node`.
+
+### 5. Session Not Resuming / "Claude Code process exited with code 1"
+
+If sessions aren't being resumed (new session ID every time), or Claude Code exits with code 1 when resuming:
+
+**Root cause:** The SDK looks for sessions at `$HOME/.claude/projects/`. Inside the container, `HOME=/home/node`, so it looks at `/home/node/.claude/projects/`.
+
+**Check the mount path:**
+```bash
+# In container-runner.ts, verify mount is to /home/node/.claude/, NOT /root/.claude/
+grep -A3 "Claude sessions" src/container-runner.ts
+```
+
+**Verify sessions are accessible:**
+```bash
+docker run --rm --entrypoint /bin/bash \
+  -v ~/.claude:/home/node/.claude \
+  nanoclaw-agent:latest -c '
+echo "HOME=$HOME"
+ls -la $HOME/.claude/projects/ 2>&1 | head -5
+'
+```
+
+**Fix:** Ensure `container-runner.ts` mounts to `/home/node/.claude/`:
+```typescript
+mounts.push({
+  hostPath: claudeDir,
+  containerPath: '/home/node/.claude',  // NOT /root/.claude
+  readonly: false
+});
+```
+
+### 6. MCP Server Failures
+
+If an MCP server fails to start, the agent may exit. Check the container logs for MCP initialization errors.
+
+## Manual Container Testing
+
+### Test the full agent flow:
+```bash
+# Set up env file
+mkdir -p data/env groups/test
+cp .env data/env/env
+
+# Run test query
+echo '{"prompt":"What is 2+2?","groupFolder":"test","chatJid":"test@g.us","isMain":false}' | \
+  docker run -i \
+  -v $(pwd)/data/env:/workspace/env-dir:ro \
+  -v $(pwd)/groups/test:/workspace/group \
+  -v $(pwd)/data/ipc:/workspace/ipc \
+  nanoclaw-agent:latest
+```
+
+### Test Claude Code directly:
+```bash
+docker run --rm --entrypoint /bin/bash \
+  -v $(pwd)/data/env:/workspace/env-dir:ro \
+  nanoclaw-agent:latest -c '
+  export $(cat /workspace/env-dir/env | xargs)
+  claude -p "Say hello" --dangerously-skip-permissions --allowedTools ""
+'
+```
+
+### Interactive shell in container:
+```bash
+docker run --rm -it --entrypoint /bin/bash nanoclaw-agent:latest
+```
+
+## SDK Options Reference
+
+The agent-runner uses these Claude Agent SDK options:
+
+```typescript
+query({
+  prompt: input.prompt,
+  options: {
+    cwd: '/workspace/group',
+    allowedTools: ['Bash', 'Read', 'Write', ...],
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,  // Required with bypassPermissions
+    settingSources: ['project'],
+    mcpServers: { ... }
+  }
+})
+```
+
+**Important:** `allowDangerouslySkipPermissions: true` is required when using `permissionMode: 'bypassPermissions'`. Without it, Claude Code exits with code 1.
+
+## Rebuilding After Changes
+
+```bash
+# Rebuild main app
+npm run build
+
+# Rebuild container (use --no-cache for clean rebuild)
+./container/build.sh
+
+# Or force full rebuild
+docker builder prune -af
+./container/build.sh
+```
+
+## Checking Container Image
+
+```bash
+# List images
+docker images
+
+# Check what's in the image
+docker run --rm --entrypoint /bin/bash nanoclaw-agent:latest -c '
+  echo "=== Node version ==="
+  node --version
+
+  echo "=== Claude Code version ==="
+  claude --version
+
+  echo "=== Installed packages ==="
+  ls /app/node_modules/
+'
+```
+
+## Session Persistence
+
+Claude sessions are stored per-group in `data/sessions/{group}/.claude/` for security isolation. Each group has its own session directory, preventing cross-group access to conversation history.
+
+**Critical:** The mount path must match the container user's HOME directory:
+- Container user: `node`
+- Container HOME: `/home/node`
+- Mount target: `/home/node/.claude/` (NOT `/root/.claude/`)
+
+To clear sessions:
+
+```bash
+# Clear all sessions for all groups
+rm -rf data/sessions/
+
+# Clear sessions for a specific group
+rm -rf data/sessions/{groupFolder}/.claude/
+
+# Also clear the session ID from NanoClaw's tracking (stored in SQLite)
+sqlite3 store/messages.db "DELETE FROM sessions WHERE group_folder = '{groupFolder}'"
+```
+
+To verify session resumption is working, check the logs for the same session ID across messages:
+```bash
+grep "Session initialized" logs/nanoclaw.log | tail -5
+# Should show the SAME session ID for consecutive messages in the same group
+```
+
+## IPC Debugging
+
+The container communicates back to the host via files in `/workspace/ipc/`:
+
+```bash
+# Check pending messages
+ls -la data/ipc/messages/
+
+# Check pending task operations
+ls -la data/ipc/tasks/
+
+# Read a specific IPC file
+cat data/ipc/messages/*.json
+
+# Check available groups (main channel only)
+cat data/ipc/main/available_groups.json
+
+# Check current tasks snapshot
+cat data/ipc/{groupFolder}/current_tasks.json
+```
+
+**IPC file types:**
+- `messages/*.json` - Agent writes: outgoing WhatsApp messages
+- `tasks/*.json` - Agent writes: task operations (schedule, pause, resume, cancel, refresh_groups)
+- `current_tasks.json` - Host writes: read-only snapshot of scheduled tasks
+- `available_groups.json` - Host writes: read-only list of WhatsApp groups (main only)
+
+## Quick Diagnostic Script
+
+Run this to check common issues:
+
+```bash
+echo "=== Checking NanoClaw Container Setup ==="
+
+echo -e "\n1. Authentication configured?"
+[ -f .env ] && (grep -q "CLAUDE_CODE_OAUTH_TOKEN=sk-" .env || grep -q "ANTHROPIC_API_KEY=sk-" .env) && echo "OK" || echo "MISSING - add CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to .env"
+
+echo -e "\n2. Env file copied for container?"
+[ -f data/env/env ] && echo "OK" || echo "MISSING - will be created on first run"
+
+echo -e "\n3. Container runtime running?"
+docker info &>/dev/null && echo "OK" || echo "NOT RUNNING - start Docker Desktop (macOS) or sudo systemctl start docker (Linux)"
+
+echo -e "\n4. Container image exists?"
+echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "OK" 2>/dev/null || echo "MISSING - run ./container/build.sh"
+
+echo -e "\n5. Session mount path correct?"
+grep -q "/home/node/.claude" src/container-runner.ts 2>/dev/null && echo "OK" || echo "WRONG - should mount to /home/node/.claude/, not /root/.claude/"
+
+echo -e "\n6. Groups directory?"
+ls -la groups/ 2>/dev/null || echo "MISSING - run setup"
+
+echo -e "\n7. Recent container logs?"
+ls -t groups/*/logs/container-*.log 2>/dev/null | head -3 || echo "No container logs yet"
+
+echo -e "\n8. Session continuity working?"
+SESSIONS=$(grep "Session initialized" logs/nanoclaw.log 2>/dev/null | tail -5 | awk '{print $NF}' | sort -u | wc -l)
+[ "$SESSIONS" -le 2 ] && echo "OK (recent sessions reusing IDs)" || echo "CHECK - multiple different session IDs, may indicate resumption issues"
+```

package/.claude/skills/get-qodo-rules/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: get-qodo-rules
+description: "Loads org- and repo-level coding rules from Qodo before code tasks begin, ensuring all generation and modification follows team standards. Use before any code generation or modification task when rules are not already loaded. Invoke when user asks to write, edit, refactor, or review code, or when starting implementation planning."
+version: 2.0.0
+allowed-tools: ["Bash"]
+triggers:
+  - "get.?qodo.?rules"
+  - "get.?rules"
+  - "load.?qodo.?rules"
+  - "load.?rules"
+  - "fetch.?qodo.?rules"
+  - "fetch.?rules"
+  - "qodo.?rules"
+  - "coding.?rules"
+  - "code.?rules"
+  - "before.?cod"
+  - "start.?coding"
+  - "write.?code"
+  - "implement"
+  - "create.*code"
+  - "build.*feature"
+  - "add.*feature"
+  - "fix.*bug"
+  - "refactor"
+  - "modify.*code"
+  - "update.*code"
+---
+
+# Get Qodo Rules Skill
+
+## Description
+
+Fetches repository-specific coding rules from the Qodo platform API before code generation or modification tasks. Rules include security requirements, coding standards, quality guidelines, and team conventions that must be applied during code generation.
+**Use** before any code generation or modification task when rules are not already loaded. Invoke when user asks to write, edit, refactor, or review code, or when starting implementation planning.
+**Skip** if "Qodo Rules Loaded" already appears in conversation context
+
+---
+
+## Workflow
+
+### Step 1: Check if Rules Already Loaded
+
+If rules are already loaded (look for "Qodo Rules Loaded" in recent messages), skip to step 6.
+
+### Step 2: Verify working in a git repository
+
+- Check that the current directory is inside a git repository. If not, inform the user that a git repository is required and exit gracefully.
+- Extract the repository scope from the git `origin` remote URL. If no remote is found, exit silently. If the URL cannot be parsed, inform the user and exit gracefully.
+- Detect module-level scope: if inside a `modules/*` subdirectory, use it as the query scope; otherwise use repository-wide scope.
+
+See [repository scope detection](references/repository-scope.md) for details.
+
+### Step 3: Verify Qodo Configuration
+
+Check that the required Qodo configuration is present. The default location is `~/.qodo/config.json`.
+
+- **API key**: Read from `~/.qodo/config.json` (`API_KEY` field). If not found, inform the user that an API key is required and provide setup instructions, then exit gracefully.
+- **Environment name**: Read from `~/.qodo/config.json` (`ENVIRONMENT_NAME` field), with `QODO_ENVIRONMENT_NAME` environment variable taking precedence. If not found, inform the user that an API key is required and provide setup instructions, then exit gracefully.
+
+### Step 4: Fetch Rules with Pagination
+
+- Fetch all pages from the API (50 rules per page) until no more results are returned.
+- On each page, handle HTTP errors and exit gracefully with a user-friendly message.
+- Accumulate all rules across pages into a single list.
+- Stop after 100 pages maximum (safety limit).
+- If no rules are found after all pages, inform the user and exit gracefully.
+
+See [pagination details](references/pagination.md) for the full algorithm and error handling.
+
+### Step 5: Format and Output Rules
+
+- Print the "📋 Qodo Rules Loaded" header with repository scope, scope context, and total rule count.
+- Group rules by severity and print each non-empty group: ERROR, WARNING, RECOMMENDATION.
+- Each rule is formatted as: `- **{name}** ({category}): {description}`
+- End output with `---`.
+
+See [output format details](references/output-format.md) for the exact format.
+
+### Step 6: Apply Rules by Severity
+
+| Severity | Enforcement | When Skipped |
+|---|---|---|
+| **ERROR** | Must comply, non-negotiable. Add comment documenting compliance (e.g., `# Following Qodo rule: No Hardcoded Credentials`) | Explain to user and ask for guidance |
+| **WARNING** | Should comply by default | Briefly explain why in response |
+| **RECOMMENDATION** | Consider when appropriate | No action needed |
+
+### Step 7: Report
+
+After code generation, inform the user about rule application:
+- **ERROR rules applied**: List which rules were followed
+- **WARNING rules skipped**: Explain why
+- **No rules applicable**: Inform: "No Qodo rules were applicable to this code change"
+- **RECOMMENDATION rules**: Mention only if they influenced a design decision
+
+---
+
+## How Scope Levels Work
+
+Determines scope from git remote and working directory (see [Step 2](#step-2-verify-working-in-a-git-repository)):
+
+**Scope Hierarchy**:
+- **Universal** (`/`) - applies everywhere
+- **Org Level** (`/org/`) - applies to organization
+- **Repo Level** (`/org/repo/`) - applies to repository
+- **Path Level** (`/org/repo/path/`) - applies to specific paths
+
+---
+
+## Configuration
+
+See `~/.qodo/config.json` for API key setup. Set `QODO_ENVIRONMENT_NAME` env var or `ENVIRONMENT_NAME` in config to select environment.
+
+---
+
+## Common Mistakes
+
+- **Re-running when rules are loaded** - Check for "Qodo Rules Loaded" in context first
+- **Missing compliance comments on ERROR rules** - ERROR rules require a comment documenting compliance
+- **Forgetting to report when no rules apply** - Always inform the user when no rules were applicable, so they know the rules system is active
+- **Not in git repo** - Inform the user that a git repository is required and exit gracefully; do not attempt code generation
+- **No API key** - Inform the user with setup instructions; set `QODO_API_KEY` or create `~/.qodo/config.json`
+- **No rules found** - Inform the user; set up rules at app.qodo.ai

package/.claude/skills/get-qodo-rules/references/output-format.md

@@ -0,0 +1,41 @@
+# Formatting and Outputting Rules
+
+## Output Structure
+
+Print the following header:
+
+```
+# 📋 Qodo Rules Loaded
+
+Scope: `{QUERY_SCOPE}`
+Rules loaded: **{TOTAL_RULES}** (universal, org level, repo level, and path level rules)
+
+These rules must be applied during code generation based on severity:
+```
+
+## Grouping by Severity
+
+Group rules into three sections and print each non-empty section:
+
+**ERROR** (`severity == "error"`):
+```
+## ❌ ERROR Rules (Must Comply) - {count}
+
+- **{name}** ({category}): {description}
+```
+
+**WARNING** (`severity == "warning"`):
+```
+## ⚠️  WARNING Rules (Should Comply) - {count}
+
+- **{name}** ({category}): {description}
+```
+
+**RECOMMENDATION** (`severity == "recommendation"`):
+```
+## 💡 RECOMMENDATION Rules (Consider) - {count}
+
+- **{name}** ({category}): {description}
+```
+
+End output with `---`.

package/.claude/skills/get-qodo-rules/references/pagination.md

@@ -0,0 +1,33 @@
+# Fetching Rules with Pagination
+
+The API returns rules in pages of 50. All pages must be fetched to ensure no rules are missed.
+
+## Algorithm
+
+1. Start with `page=1`, `page_size=50`, accumulate results in an empty list
+2. Request: `GET {API_URL}/rules?scopes={ENCODED_SCOPE}&state=active&page={PAGE}&page_size=50`
+   - Header: `Authorization: Bearer {API_KEY}`
+3. On non-200 response, handle the error and exit gracefully:
+   - `401` — invalid/expired API key
+   - `403` — access forbidden
+   - `404` — endpoint not found (check `QODO_ENVIRONMENT_NAME`)
+   - `429` — rate limit exceeded
+   - `5xx` — API temporarily unavailable
+   - connection error — check internet connection
+4. Parse `rules` array from JSON response body
+5. Append page rules to accumulated list
+6. If rules returned on this page < 50 → last page, stop
+7. Otherwise increment page and repeat from step 2
+8. Safety limit: stop after 100 pages (5000 rules max)
+
+## API URL
+
+Construct `{API_URL}` from `ENVIRONMENT_NAME` (read from `~/.qodo/config.json`):
+
+| `ENVIRONMENT_NAME` | `{API_URL}` |
+|---|---|
+| set (e.g. `staging`) | `https://qodo-platform.staging.qodo.ai/rules/v1` |
+
+## After Fetching
+
+If total rules == 0, inform the user no rules are configured for the repository scope and exit gracefully.

package/.claude/skills/get-qodo-rules/references/repository-scope.md

@@ -0,0 +1,26 @@
+# Repository Scope Detection
+
+## Extracting Repository Scope from Git Remote URL
+
+Parse the `origin` remote URL to derive the scope path. Both URL formats are supported:
+
+- SSH: `git@github.com:org/repo.git` → `/org/repo/`
+- HTTPS: `https://github.com/org/repo.git` → `/org/repo/`
+
+If no remote is found, exit silently. If the URL cannot be parsed, inform the user and exit gracefully.
+
+## Module-Level Scope Detection
+
+If the current working directory is inside a `modules/*` subdirectory relative to the repository root, use it as the query scope:
+
+- `modules/rules/src/service.py` → query scope: `/org/repo/modules/rules/`
+- repository root or any other path → query scope: `/org/repo/`
+
+## Scope Hierarchy
+
+The API returns all rules matching the query scope via prefix matching:
+
+| Query scope | Rules returned |
+|---|---|
+| `/org/repo/modules/rules/` | universal + org + repo + path-level rules |
+| `/org/repo/` | universal + org + repo-level rules |