@rozek/nanoclaw 1.2.17

package/groups/global/CLAUDE.md

@@ -0,0 +1,58 @@
+# Andy
+
+You are Andy, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
+
+## What You Can Do
+
+- Answer questions and have conversations
+- Search the web and fetch content from URLs
+- **Browse the web** with `agent-browser` — open pages, click, fill forms, take screenshots, extract data (run `agent-browser open <url>` to start, then `agent-browser snapshot -i` to see interactive elements)
+- Read and write files in your workspace
+- Run bash commands in your sandbox
+- Schedule tasks to run later or on a recurring basis
+- Send messages back to the chat
+
+## Communication
+
+Your output is sent to the user or group.
+
+You also have `mcp__nanoclaw__send_message` which sends a message immediately while you're still working. This is useful when you want to acknowledge a request before starting longer work.
+
+### Internal thoughts
+
+If part of your output is internal reasoning rather than something for the user, wrap it in `<internal>` tags:
+
+```
+<internal>Compiled all three reports, ready to summarize.</internal>
+
+Here are the key findings from the research...
+```
+
+Text inside `<internal>` tags is logged but not sent to the user. If you've already sent the key information via `send_message`, you can wrap the recap in `<internal>` to avoid sending it again.
+
+### Sub-agents and teammates
+
+When working as a sub-agent or teammate, only use `send_message` if instructed to by the main agent.
+
+## Your Workspace
+
+Files you create are saved in `/workspace/group/`. Use this for notes, research, or anything that should persist.
+
+## Memory
+
+The `conversations/` folder contains searchable history of past conversations. Use this to recall context from previous sessions.
+
+When you learn something important:
+- Create files for structured data (e.g., `customers.md`, `preferences.md`)
+- Split files larger than 500 lines into folders
+- Keep an index in your memory for the files you create
+
+## Message Formatting
+
+NEVER use markdown. Only use WhatsApp/Telegram formatting:
+- *single asterisks* for bold (NEVER **double asterisks**)
+- _underscores_ for italic
+- • bullet points
+- ```triple backticks``` for code
+
+No ## headings. No [links](url). No **double stars**.

package/groups/main/CLAUDE.md

@@ -0,0 +1,246 @@
+# Andy
+
+You are Andy, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
+
+## What You Can Do
+
+- Answer questions and have conversations
+- Search the web and fetch content from URLs
+- **Browse the web** with `agent-browser` — open pages, click, fill forms, take screenshots, extract data (run `agent-browser open <url>` to start, then `agent-browser snapshot -i` to see interactive elements)
+- Read and write files in your workspace
+- Run bash commands in your sandbox
+- Schedule tasks to run later or on a recurring basis
+- Send messages back to the chat
+
+## Communication
+
+Your output is sent to the user or group.
+
+You also have `mcp__nanoclaw__send_message` which sends a message immediately while you're still working. This is useful when you want to acknowledge a request before starting longer work.
+
+### Internal thoughts
+
+If part of your output is internal reasoning rather than something for the user, wrap it in `<internal>` tags:
+
+```
+<internal>Compiled all three reports, ready to summarize.</internal>
+
+Here are the key findings from the research...
+```
+
+Text inside `<internal>` tags is logged but not sent to the user. If you've already sent the key information via `send_message`, you can wrap the recap in `<internal>` to avoid sending it again.
+
+### Sub-agents and teammates
+
+When working as a sub-agent or teammate, only use `send_message` if instructed to by the main agent.
+
+## Memory
+
+The `conversations/` folder contains searchable history of past conversations. Use this to recall context from previous sessions.
+
+When you learn something important:
+- Create files for structured data (e.g., `customers.md`, `preferences.md`)
+- Split files larger than 500 lines into folders
+- Keep an index in your memory for the files you create
+
+## WhatsApp Formatting (and other messaging apps)
+
+Do NOT use markdown headings (##) in WhatsApp messages. Only use:
+- *Bold* (single asterisks) (NEVER **double asterisks**)
+- _Italic_ (underscores)
+- • Bullets (bullet points)
+- ```Code blocks``` (triple backticks)
+
+Keep messages clean and readable for WhatsApp.
+
+---
+
+## Admin Context
+
+This is the **main channel**, which has elevated privileges.
+
+## Container Mounts
+
+Main has read-only access to the project and read-write access to its group folder:
+
+| Container Path | Host Path | Access |
+|----------------|-----------|--------|
+| `/workspace/project` | Project root | read-only |
+| `/workspace/group` | `groups/main/` | read-write |
+
+Key paths inside the container:
+- `/workspace/project/store/messages.db` - SQLite database
+- `/workspace/project/store/messages.db` (registered_groups table) - Group config
+- `/workspace/project/groups/` - All group folders
+
+---
+
+## Managing Groups
+
+### Finding Available Groups
+
+Available groups are provided in `/workspace/ipc/available_groups.json`:
+
+```json
+{
+  "groups": [
+    {
+      "jid": "120363336345536173@g.us",
+      "name": "Family Chat",
+      "lastActivity": "2026-01-31T12:00:00.000Z",
+      "isRegistered": false
+    }
+  ],
+  "lastSync": "2026-01-31T12:00:00.000Z"
+}
+```
+
+Groups are ordered by most recent activity. The list is synced from WhatsApp daily.
+
+If a group the user mentions isn't in the list, request a fresh sync:
+
+```bash
+echo '{"type": "refresh_groups"}' > /workspace/ipc/tasks/refresh_$(date +%s).json
+```
+
+Then wait a moment and re-read `available_groups.json`.
+
+**Fallback**: Query the SQLite database directly:
+
+```bash
+sqlite3 /workspace/project/store/messages.db "
+  SELECT jid, name, last_message_time
+  FROM chats
+  WHERE jid LIKE '%@g.us' AND jid != '__group_sync__'
+  ORDER BY last_message_time DESC
+  LIMIT 10;
+"
+```
+
+### Registered Groups Config
+
+Groups are registered in the SQLite `registered_groups` table:
+
+```json
+{
+  "1234567890-1234567890@g.us": {
+    "name": "Family Chat",
+    "folder": "whatsapp_family-chat",
+    "trigger": "@Andy",
+    "added_at": "2024-01-31T12:00:00.000Z"
+  }
+}
+```
+
+Fields:
+- **Key**: The chat JID (unique identifier — WhatsApp, Telegram, Slack, Discord, etc.)
+- **name**: Display name for the group
+- **folder**: Channel-prefixed folder name under `groups/` for this group's files and memory
+- **trigger**: The trigger word (usually same as global, but could differ)
+- **requiresTrigger**: Whether `@trigger` prefix is needed (default: `true`). Set to `false` for solo/personal chats where all messages should be processed
+- **isMain**: Whether this is the main control group (elevated privileges, no trigger required)
+- **added_at**: ISO timestamp when registered
+
+### Trigger Behavior
+
+- **Main group** (`isMain: true`): No trigger needed — all messages are processed automatically
+- **Groups with `requiresTrigger: false`**: No trigger needed — all messages processed (use for 1-on-1 or solo chats)
+- **Other groups** (default): Messages must start with `@AssistantName` to be processed
+
+### Adding a Group
+
+1. Query the database to find the group's JID
+2. Use the `register_group` MCP tool with the JID, name, folder, and trigger
+3. Optionally include `containerConfig` for additional mounts
+4. The group folder is created automatically: `/workspace/project/groups/{folder-name}/`
+5. Optionally create an initial `CLAUDE.md` for the group
+
+Folder naming convention — channel prefix with underscore separator:
+- WhatsApp "Family Chat" → `whatsapp_family-chat`
+- Telegram "Dev Team" → `telegram_dev-team`
+- Discord "General" → `discord_general`
+- Slack "Engineering" → `slack_engineering`
+- Use lowercase, hyphens for the group name part
+
+#### Adding Additional Directories for a Group
+
+Groups can have extra directories mounted. Add `containerConfig` to their entry:
+
+```json
+{
+  "1234567890@g.us": {
+    "name": "Dev Team",
+    "folder": "dev-team",
+    "trigger": "@Andy",
+    "added_at": "2026-01-31T12:00:00Z",
+    "containerConfig": {
+      "additionalMounts": [
+        {
+          "hostPath": "~/projects/webapp",
+          "containerPath": "webapp",
+          "readonly": false
+        }
+      ]
+    }
+  }
+}
+```
+
+The directory will appear at `/workspace/extra/webapp` in that group's container.
+
+#### Sender Allowlist
+
+After registering a group, explain the sender allowlist feature to the user:
+
+> This group can be configured with a sender allowlist to control who can interact with me. There are two modes:
+>
+> - **Trigger mode** (default): Everyone's messages are stored for context, but only allowed senders can trigger me with @{AssistantName}.
+> - **Drop mode**: Messages from non-allowed senders are not stored at all.
+>
+> For closed groups with trusted members, I recommend setting up an allow-only list so only specific people can trigger me. Want me to configure that?
+
+If the user wants to set up an allowlist, edit `~/.config/nanoclaw/sender-allowlist.json` on the host:
+
+```json
+{
+  "default": { "allow": "*", "mode": "trigger" },
+  "chats": {
+    "<chat-jid>": {
+      "allow": ["sender-id-1", "sender-id-2"],
+      "mode": "trigger"
+    }
+  },
+  "logDenied": true
+}
+```
+
+Notes:
+- Your own messages (`is_from_me`) explicitly bypass the allowlist in trigger checks. Bot messages are filtered out by the database query before trigger evaluation, so they never reach the allowlist.
+- If the config file doesn't exist or is invalid, all senders are allowed (fail-open)
+- The config file is on the host at `~/.config/nanoclaw/sender-allowlist.json`, not inside the container
+
+### Removing a Group
+
+1. Read `/workspace/project/data/registered_groups.json`
+2. Remove the entry for that group
+3. Write the updated JSON back
+4. The group folder and its files remain (don't delete them)
+
+### Listing Groups
+
+Read `/workspace/project/data/registered_groups.json` and format it nicely.
+
+---
+
+## Global Memory
+
+You can read and write to `/workspace/project/groups/global/CLAUDE.md` for facts that should apply to all groups. Only update global memory when explicitly asked to "remember this globally" or similar.
+
+---
+
+## Scheduling for Other Groups
+
+When scheduling tasks for other groups, use the `target_group_jid` parameter with the group's JID from `registered_groups.json`:
+- `schedule_task(prompt: "...", schedule_type: "cron", schedule_value: "0 9 * * 1", target_group_jid: "120363336345536173@g.us")`
+
+The task will run in that group's context with access to their files and memory.

package/launchd/com.nanoclaw.plist

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.nanoclaw</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{NODE_PATH}}</string>
+        <string>{{PROJECT_ROOT}}/dist/index.js</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>{{PROJECT_ROOT}}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>{{HOME}}/.local/bin:/usr/local/bin:/usr/bin:/bin</string>
+        <key>HOME</key>
+        <string>{{HOME}}</string>
+        <key>ASSISTANT_NAME</key>
+        <string>Andy</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>{{PROJECT_ROOT}}/logs/nanoclaw.log</string>
+    <key>StandardErrorPath</key>
+    <string>{{PROJECT_ROOT}}/logs/nanoclaw.error.log</string>
+</dict>
+</plist>

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@rozek/nanoclaw",
+  "version": "1.2.17",
+  "description": "Personal Claude assistant. Lightweight, secure, customizable.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "nanoclaw": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:fix": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "prepare": "husky",
+    "setup": "tsx setup/index.ts",
+    "auth": "tsx src/whatsapp-auth.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.8.1",
+    "cron-parser": "^5.5.0",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "husky": "^9.1.7",
+    "prettier": "^3.8.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/repo-tokens/README.md

@@ -0,0 +1,113 @@
+# Repo Tokens
+
+A GitHub Action that calculates the size of your codebase in terms of tokens and updates a badge in your README.
+
+<p>
+  <img src="examples/green.svg" alt="tokens 12.4k">&nbsp;
+  <img src="examples/yellow-green.svg" alt="tokens 74.8k">&nbsp;
+  <img src="examples/yellow.svg" alt="tokens 120k">&nbsp;
+  <img src="examples/red.svg" alt="tokens 158k">
+</p>
+
+## Usage
+
+```yaml
+- uses: qwibitai/nanoclaw/repo-tokens@v1
+  with:
+    include: 'src/**/*.ts'
+    exclude: 'src/**/*.test.ts'
+```
+
+This counts tokens using [tiktoken](https://github.com/openai/tiktoken) and writes the result between HTML comment markers in your README:
+
+The badge color reflects what percentage of an LLMs context window the codebase fills (context window size is configurable, defaults to 200k which is the size of Claude Opus). Green for under 30%, yellow-green for 30%-50%, yellow for 50%-70%, red for 70%+.
+
+## Why
+
+Small codebases were always a good thing. With coding agents, there's now a huge advantage to having a codebase small enough that an agent can hold the full thing in context.
+
+This badge gives some indication of how easy it will be to work with an agent on the codebase, and will hopefully be a visual reminder to avoid bloat.
+
+## Examples
+
+Repos using repo-tokens:
+
+| Repo | Badge |
+|------|-------|
+| [NanoClaw](https://github.com/qwibitai/NanoClaw) | ![tokens](https://raw.githubusercontent.com/qwibitai/NanoClaw/main/repo-tokens/badge.svg) |
+
+### Full workflow example
+
+```yaml
+name: Update token count
+
+on:
+  push:
+    branches: [main]
+    paths: ['src/**']
+
+permissions:
+  contents: write
+
+jobs:
+  update-tokens:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - uses: qwibitai/nanoclaw/repo-tokens@v1
+        id: tokens
+        with:
+          include: 'src/**/*.ts'
+          exclude: 'src/**/*.test.ts'
+          badge-path: '.github/badges/tokens.svg'
+
+      - name: Commit if changed
+        run: |
+          git add README.md .github/badges/tokens.svg
+          git diff --cached --quiet && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "docs: update token count to ${{ steps.tokens.outputs.badge }}"
+          git push
+```
+
+### README setup
+
+Add markers where you want the token count text to appear:
+
+```html
+<!-- token-count --><!-- /token-count -->
+```
+
+The action replaces everything between the markers with the token count.
+
+## Inputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `include` | *required* | Glob patterns for files to count (space-separated) |
+| `exclude` | `''` | Glob patterns to exclude (space-separated) |
+| `context-window` | `200000` | Context window size for percentage calculation |
+| `readme` | `README.md` | Path to README file |
+| `encoding` | `cl100k_base` | Tiktoken encoding name |
+| `marker` | `token-count` | HTML comment marker name |
+| `badge-path` | `''` | Path to write SVG badge (empty = no SVG) |
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `tokens` | Total token count (e.g., `34940`) |
+| `percentage` | Percentage of context window (e.g., `17`) |
+| `badge` | The formatted text that was inserted (e.g., `34.9k tokens · 17% of context window`) |
+
+## How it works
+
+Composite GitHub Action. Installs tiktoken, runs ~60 lines of inline Python. Takes about 10 seconds.
+
+The action counts tokens and updates the README but does not commit. Your workflow decides the git strategy.

package/repo-tokens/action.yml

@@ -0,0 +1,186 @@
+name: Repo Tokens
+description: Count codebase tokens with tiktoken and update a README badge
+
+inputs:
+  include:
+    description: 'Glob patterns for files to count (space-separated)'
+    required: true
+  exclude:
+    description: 'Glob patterns to exclude (space-separated)'
+    required: false
+    default: ''
+  context-window:
+    description: 'Context window size for percentage calculation'
+    required: false
+    default: '200000'
+  readme:
+    description: 'Path to README file'
+    required: false
+    default: 'README.md'
+  encoding:
+    description: 'Tiktoken encoding name'
+    required: false
+    default: 'cl100k_base'
+  marker:
+    description: 'HTML comment marker name'
+    required: false
+    default: 'token-count'
+  badge-path:
+    description: 'Path to write SVG badge (empty = no SVG)'
+    required: false
+    default: ''
+
+outputs:
+  tokens:
+    description: 'Total token count'
+    value: ${{ steps.count.outputs.tokens }}
+  percentage:
+    description: 'Percentage of context window'
+    value: ${{ steps.count.outputs.percentage }}
+  badge:
+    description: 'Badge text that was inserted'
+    value: ${{ steps.count.outputs.badge }}
+
+runs:
+  using: composite
+  steps:
+    - name: Install tiktoken
+      shell: bash
+      run: pip install tiktoken
+
+    - name: Count tokens and update README
+      id: count
+      shell: python
+      env:
+        INPUT_INCLUDE: ${{ inputs.include }}
+        INPUT_EXCLUDE: ${{ inputs.exclude }}
+        INPUT_CONTEXT_WINDOW: ${{ inputs.context-window }}
+        INPUT_README: ${{ inputs.readme }}
+        INPUT_ENCODING: ${{ inputs.encoding }}
+        INPUT_MARKER: ${{ inputs.marker }}
+        INPUT_BADGE_PATH: ${{ inputs.badge-path }}
+      run: |
+        import glob, os, re, tiktoken
+
+        include_patterns = os.environ["INPUT_INCLUDE"].split()
+        exclude_patterns = os.environ["INPUT_EXCLUDE"].split()
+        context_window = int(os.environ["INPUT_CONTEXT_WINDOW"])
+        readme_path = os.environ["INPUT_README"]
+        encoding_name = os.environ["INPUT_ENCODING"]
+        marker = os.environ["INPUT_MARKER"]
+        badge_path = os.environ.get("INPUT_BADGE_PATH", "").strip()
+
+        # Expand globs
+        included = set()
+        for pattern in include_patterns:
+            included.update(glob.glob(pattern, recursive=True))
+
+        excluded = set()
+        for pattern in exclude_patterns:
+            excluded.update(glob.glob(pattern, recursive=True))
+
+        files = sorted(included - excluded)
+        files = [f for f in files if os.path.isfile(f)]
+
+        # Count tokens
+        enc = tiktoken.get_encoding(encoding_name)
+        total = 0
+        for path in files:
+            try:
+                with open(path, "r", encoding="utf-8", errors="ignore") as f:
+                    total += len(enc.encode(f.read()))
+            except Exception as e:
+                print(f"Skipping {path}: {e}")
+
+        # Format
+        if total >= 100000:
+            display = f"{round(total / 1000)}k"
+        elif total >= 1000:
+            display = f"{total / 1000:.1f}k"
+        else:
+            display = str(total)
+
+        pct = round(total / context_window * 100)
+        badge = f"{display} tokens \u00b7 {pct}% of context window"
+
+        print(f"Files: {len(files)}, Tokens: {total}, Badge: {badge}")
+
+        # Update README (text between markers)
+        marker_re = re.compile(
+            rf"(<!--\s*{re.escape(marker)}\s*-->).*?(<!--\s*/{re.escape(marker)}\s*-->)",
+            re.DOTALL,
+        )
+
+        with open(readme_path, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        repo_tokens_url = "https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens"
+        linked_badge = f'<a href="{repo_tokens_url}">{badge}</a>'
+        new_content = marker_re.sub(rf"\1{linked_badge}\2", content)
+
+        if new_content != content:
+            with open(readme_path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+            print("README updated")
+        else:
+            print("No change to README")
+
+        # Generate SVG badge
+        if badge_path:
+            label_text = "tokens"
+            value_text = display
+            full_desc = f"{display} tokens, {pct}% of context window"
+
+            cw = 7.0
+            label_w = round(len(label_text) * cw) + 10
+            value_w = round(len(value_text) * cw) + 10
+            total_w = label_w + value_w
+
+            if pct < 30:
+                color = "#4c1"
+            elif pct < 50:
+                color = "#97ca00"
+            elif pct < 70:
+                color = "#dfb317"
+            else:
+                color = "#e05d44"
+
+            lx = label_w // 2
+            vx = label_w + value_w // 2
+
+            repo_tokens_url = "https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens"
+
+            svg = f'''<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="{total_w}" height="20" role="img" aria-label="{full_desc}">
+          <title>{full_desc}</title>
+          <linearGradient id="s" x2="0" y2="100%">
+            <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+            <stop offset="1" stop-opacity=".1"/>
+          </linearGradient>
+          <clipPath id="r">
+            <rect width="{total_w}" height="20" rx="3" fill="#fff"/>
+          </clipPath>
+          <a xlink:href="{repo_tokens_url}">
+            <g clip-path="url(#r)">
+              <rect width="{label_w}" height="20" fill="#555"/>
+              <rect x="{label_w}" width="{value_w}" height="20" fill="{color}"/>
+              <rect width="{total_w}" height="20" fill="url(#s)"/>
+              <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+                <text aria-hidden="true" x="{lx}" y="15" fill="#010101" fill-opacity=".3">{label_text}</text>
+                <text x="{lx}" y="14">{label_text}</text>
+                <text aria-hidden="true" x="{vx}" y="15" fill="#010101" fill-opacity=".3">{value_text}</text>
+                <text x="{vx}" y="14">{value_text}</text>
+              </g>
+            </g>
+          </a>
+        </svg>'''
+
+            os.makedirs(os.path.dirname(badge_path) or ".", exist_ok=True)
+            with open(badge_path, "w", encoding="utf-8") as f:
+                f.write(svg)
+            print(f"Badge SVG written to {badge_path}")
+
+        # Set outputs
+        with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+            f.write(f"tokens={total}\n")
+            f.write(f"percentage={pct}\n")
+            f.write(f"badge={badge}\n")