@rozek/nanoclaw 1.2.17

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to NanoClaw will be documented in this file.
+
+## [1.2.0](https://github.com/qwibitai/nanoclaw/compare/v1.1.6...v1.2.0)
+
+[BREAKING] WhatsApp removed from core, now a skill. Run `/add-whatsapp` to re-add (existing auth/groups preserved).
+- **fix:** Prevent scheduled tasks from executing twice when container runtime exceeds poll interval (#138, #669)

package/CLAUDE.md

@@ -0,0 +1,64 @@
+# NanoClaw
+
+Personal Claude assistant. See [README.md](README.md) for philosophy and setup. See [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) for architecture decisions.
+
+## Quick Context
+
+Single Node.js process with skill-based channel system. Channels (WhatsApp, Telegram, Slack, Discord, Gmail) are skills that self-register at startup. Messages route to Claude Agent SDK running in containers (Linux VMs). Each group has isolated filesystem and memory.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Orchestrator: state, message loop, agent invocation |
+| `src/channels/registry.ts` | Channel registry (self-registration at startup) |
+| `src/ipc.ts` | IPC watcher and task processing |
+| `src/router.ts` | Message formatting and outbound routing |
+| `src/config.ts` | Trigger pattern, paths, intervals |
+| `src/container-runner.ts` | Spawns agent containers with mounts |
+| `src/task-scheduler.ts` | Runs scheduled tasks |
+| `src/db.ts` | SQLite operations |
+| `groups/{name}/CLAUDE.md` | Per-group memory (isolated) |
+| `container/skills/agent-browser.md` | Browser automation tool (available to all agents via Bash) |
+
+## Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| `/setup` | First-time installation, authentication, service configuration |
+| `/customize` | Adding channels, integrations, changing behavior |
+| `/debug` | Container issues, logs, troubleshooting |
+| `/update-nanoclaw` | Bring upstream NanoClaw updates into a customized install |
+| `/qodo-pr-resolver` | Fetch and fix Qodo PR review issues interactively or in batch |
+| `/get-qodo-rules` | Load org- and repo-level coding rules from Qodo before code tasks |
+
+## Development
+
+Run commands directly—don't tell the user to run them.
+
+```bash
+npm run dev          # Run with hot reload
+npm run build        # Compile TypeScript
+./container/build.sh # Rebuild agent container
+```
+
+Service management:
+```bash
+# macOS (launchd)
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # restart
+
+# Linux (systemd)
+systemctl --user start nanoclaw
+systemctl --user stop nanoclaw
+systemctl --user restart nanoclaw
+```
+
+## Troubleshooting
+
+**WhatsApp not connecting after upgrade:** WhatsApp is now a separate channel fork, not bundled in core. Run `/add-whatsapp` (or `git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git && git fetch whatsapp main && (git merge whatsapp/main || { git checkout --theirs package-lock.json && git add package-lock.json && git merge --continue; }) && npm run build`) to install it. Existing auth credentials and groups are preserved.
+
+## Container Build Cache
+
+The container buildkit caches the build context aggressively. `--no-cache` alone does NOT invalidate COPY steps — the builder's volume retains stale files. To force a truly clean rebuild, prune the builder then re-run `./container/build.sh`.

package/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+## Source Code Changes
+
+**Accepted:** Bug fixes, security fixes, simplifications, reducing code.
+
+**Not accepted:** Features, capabilities, compatibility, enhancements. These should be skills.
+
+## Skills
+
+A [skill](https://code.claude.com/docs/en/skills) is a markdown file in `.claude/skills/` that teaches Claude Code how to transform a NanoClaw installation.
+
+A PR that contributes a skill should not modify any source files.
+
+Your skill should contain the **instructions** Claude follows to add the feature—not pre-built code. See `/add-telegram` for a good example.
+
+### Why?
+
+Every user should have clean and minimal code that does exactly what they need. Skills let users selectively add features to their fork without inheriting code for features they don't want.
+
+### Testing
+
+Test your skill by running it on a fresh clone before submitting.

package/CONTRIBUTORS.md

@@ -0,0 +1,15 @@
+# Contributors
+
+Thanks to everyone who has contributed to NanoClaw!
+
+- [Alakazam03](https://github.com/Alakazam03) — Vaibhav Aggarwal
+- [tydev-new](https://github.com/tydev-new)
+- [pottertech](https://github.com/pottertech) — Skip Potter
+- [rgarcia](https://github.com/rgarcia) — Rafael
+- [AmaxGuan](https://github.com/AmaxGuan) — Lingfeng Guan
+- [happydog-intj](https://github.com/happydog-intj) — happy dog
+- [bindoon](https://github.com/bindoon) — 潕量
+- [taslim](https://github.com/taslim) — Taslim
+- [baijunjie](https://github.com/baijunjie) — BaiJunjie
+- [Michaelliv](https://github.com/Michaelliv) — Michael
+- [kk17](https://github.com/kk17) — Kyle Zhike Chen

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NanoClaw_with_Web-Support.md

@@ -0,0 +1,290 @@
+# NanoClaw with Web Support
+
+This document describes the changes added in the [rozek/nanoclaw](https://github.com/rozek/nanoclaw) fork of [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw). It serves as installation guide, feature reference, and API documentation.
+
+---
+
+## What's New
+
+Two files were added or changed relative to the upstream project:
+
+| File | What changed |
+|------|-------------|
+| `src/cli.ts` | **New.** CLI entry point — enables `npx @rozek/nanoclaw` |
+| `src/channels/web.ts` | **New.** Built-in HTTP server with a full browser chat UI |
+| `package.json` | Added `"bin": {"nanoclaw": "dist/cli.js"}` for `npx` support |
+
+Everything else remains unchanged. No existing file was modified in a breaking way.
+
+---
+
+## Quick Start (npx)
+
+No cloning, no `npm install` — just run:
+
+```bash
+npx @rozek/nanoclaw
+```
+
+Then open **http://localhost:3099** in your browser.
+
+### Prerequisites
+
+| Requirement | How to check | Notes |
+|-------------|-------------|-------|
+| **Node.js ≥ 20** | `node --version` | |
+| **Claude Code** | `claude --version` | `npm install -g @anthropic-ai/claude-code` |
+| **Container runtime** | `docker info` *or* `container --version` | Docker Desktop **or** macOS Sequoia 15+ Apple Container Runtime |
+
+> **No API key required** if you have a Claude Pro or Max subscription — NanoClaw uses Claude Code, which is included in those plans.
+
+---
+
+## Installation & Usage
+
+### Simplest start
+
+```bash
+npx @rozek/nanoclaw
+```
+
+Auto-detects the container runtime (Docker first, then Apple Container). Binds to `0.0.0.0:3099`.
+
+### Common options
+
+```bash
+# Custom port
+npx @rozek/nanoclaw --port 8080
+
+# Custom workspace (directory NanoClaw works in)
+npx @rozek/nanoclaw --workspace ~/my-workspace
+
+# Token protection — recommended when accessible from the LAN
+npx @rozek/nanoclaw --token mySecretToken
+
+# Explicit container runtime
+npx @rozek/nanoclaw --sandbox docker
+npx @rozek/nanoclaw --sandbox apple
+
+# With an Anthropic API key (for users without Pro/Max)
+npx @rozek/nanoclaw --key sk-ant-...
+
+# Combine options
+npx @rozek/nanoclaw --port 8080 --workspace ~/my-workspace --token mySecretToken --sandbox docker
+```
+
+### All CLI options
+
+```
+Options:
+  --host <address>      Bind address for the web channel  (default: 0.0.0.0)
+  --port <number>       Port for the web channel           (default: 3099)
+  --workspace <path>    Workspace directory                (default: current directory)
+  --key <api-key>       Anthropic API key
+                          Not required with Claude Pro/Max — NanoClaw uses
+                          Claude Code, which is included in those plans.
+  --token <token>       Access token for the web interface (default: no protection)
+                          Clients supply it via:
+                            Authorization: Bearer <token>
+                            ?token=<value> query parameter
+                            or a session cookie
+  --sandbox <type>      Container runtime: "docker" or "apple"
+                          Defaults to auto-detect (docker → apple).
+  -h, --help            Show this help and exit
+```
+
+### Environment variables
+
+CLI flags take precedence. Alternatively, set environment variables:
+
+```bash
+NANOCLAW_HOST=0.0.0.0
+NANOCLAW_PORT=3099
+NANOCLAW_TOKEN=mySecretToken
+NANOCLAW_KEY=sk-ant-...
+NANOCLAW_WORKSPACE=/path/to/workspace
+NANOCLAW_SANDBOX=docker   # or: apple
+```
+
+---
+
+## Web Channel Features
+
+### UI & Design
+
+- **Light theme** — clean, distraction-free (#f5f5f5 background, #ffffff header/cards)
+- **Full-viewport layout** — always fills the screen
+- **Responsive** — desktop: fixed sidebar; mobile: sidebar as overlay with backdrop
+
+### Rich Content Rendering
+
+Bot responses are rendered with full Markdown support:
+
+| Library | Purpose |
+|---------|---------|
+| [marked.js](https://marked.js.org) | GitHub Flavored Markdown |
+| [KaTeX](https://katex.org) | Inline (`$...$`) and block (`$$...$$`) math formulas |
+| [highlight.js](https://highlightjs.org) | Syntax highlighting (TypeScript, Java, and many more) |
+| [Mermaid](https://mermaid.js.org) | Flowcharts, sequence diagrams, etc. |
+
+### Multi-Session Chat
+
+- Unlimited parallel chat sessions per browser
+- Sessions are listed in the sidebar, freely sortable by most recent activity
+- Each session has an editable name (double-click or pencil icon; default: date+time)
+- Sessions persist in `localStorage` and SQLite — survive browser reloads and server restarts
+- Sessions from other devices appear automatically in the sidebar (polled every 5 s)
+- Unread message indicators (blue dot) per session, persisted in `localStorage`
+- Sessions can be deleted (removes all messages from DB and `localStorage`)
+
+### Session Name Sync
+
+Conflict-free name synchronisation across devices:
+
+- Every rename carries a `nameUpdatedAt` UNIX timestamp
+- Server-side guard: `UPDATE … WHERE excluded.name_updated_at >= chats.name_updated_at`
+- On SSE connect, the client pushes its local name; if it is newer than the server's name, the server adopts it
+
+### Message History
+
+- Local `localStorage` cache (`hist:{sid}`) for instant display on load
+- Full conversation history served from SQLite via `GET /history?sid=…`
+- Both user messages and bot replies are persisted and synced across devices
+- Individual messages can be deleted (trash icon; removes from DOM, cache, and DB)
+
+### Real-Time Updates (Server-Sent Events)
+
+All live updates arrive over a single SSE connection (`GET /events?sid=…`):
+
+| Event | Payload | Purpose |
+|-------|---------|---------|
+| `message` | `{"text":"…","id":"…"}` | Append bot reply |
+| `typing` | `"true"` / `"false"` | Show/hide typing indicator |
+| `status` | `{"tool":"…","input":"…"}` or `null` | Display active tool (e.g. "searching…") |
+| `cwd` | path string | Update working-directory display in header |
+
+On connect, the server immediately sends the current `typing`, `status`, and `cwd` state so reconnects are seamless.
+
+### Working Directory (CWD)
+
+- Current working directory shown in the header: `NanoClaw — IP:Port — /Topics/TopicName`
+- Automatically detected from agent output (`switching to topic: <name>`)
+- Persisted in `chats.cwd` (SQLite) — survives server restarts
+- Also cached in `localStorage` per session
+
+### File Upload
+
+- Drag files into the browser window
+- Files are written to the session's current working directory (or group root if no CWD)
+- Maximum file size: 10 MB
+
+### Cancel In-Progress Requests
+
+- A **Cancel** button appears while the agent is processing
+- Sends `POST /cancel?sid=…` to abort the current request
+
+### Access Control
+
+Token-based authentication is optional but recommended when NanoClaw is reachable from the LAN:
+
+```bash
+npx @rozek/nanoclaw --token mySecretToken
+```
+
+Clients authenticate via:
+1. `Authorization: Bearer mySecretToken` header
+2. `?token=mySecretToken` URL query parameter (sets an HttpOnly session cookie)
+3. The HttpOnly session cookie set after step 2
+
+---
+
+## HTTP API Reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/` | Serves the web UI (HTML) |
+| `GET` | `/events?sid=…` | SSE stream for real-time updates |
+| `GET` | `/sessions` | All web sessions (JSON) |
+| `GET` | `/history?sid=…` | Conversation history (JSON) |
+| `GET` | `/favicon.ico` | Favicon (ICO) |
+| `GET` | `/favicon.png` | Favicon (PNG) |
+| `GET` | `/apple-touch-icon.png` | iOS home-screen icon |
+| `POST` | `/message` | Send a chat message |
+| `POST` | `/session-name` | Rename a session |
+| `POST` | `/delete-session` | Delete a session and all its messages |
+| `POST` | `/delete-message` | Delete a single message `{sid, id}` |
+| `POST` | `/cwd` | Set the working directory for a session |
+| `POST` | `/upload` | Upload a file (Base64-encoded body) |
+| `POST` | `/cancel?sid=…` | Cancel the active request for a session |
+
+---
+
+## Architecture
+
+```
+Browser                        Server (web.ts)               DB (SQLite)
+───────                        ───────────────               ───────────
+GET /          ←─────────────  Embedded HTML/CSS/JS
+GET /events    ←── SSE ──────  sseClients Map
+POST /message  ────────────→   onMessage() → agent run
+                               agent replies → broadcastToSession()
+GET /sessions  ←── poll 5s ─   getAllChats() + sessionCwds   chats table
+POST /session-name  ────────→  updateChatName() (with guard) chats.name
+GET /history   ←─────────────  getConversation()             messages table
+POST /delete-session  ──────→  deleteChat()                  chats + messages
+POST /delete-message  ──────→  deleteMessage(id)             messages table
+POST /cwd      ────────────→   setCwd() → broadcast          chats.cwd
+POST /upload   ────────────→   fs.writeFile() into CWD dir
+POST /cancel   ────────────→   onCancelRequest()
+```
+
+### In-Memory Server State
+
+| Variable | Type | Content |
+|----------|------|---------|
+| `sseClients` | `Map<sid, Set<Response>>` | Open SSE connections per session |
+| `sessionCwds` | `Map<sid, string>` | Current CWD per session |
+| `sessionTyping` | `Map<sid, boolean>` | Whether the agent is processing |
+| `sessionStatus` | `Map<sid, string\|null>` | Last tool-status payload |
+| `registeredSessions` | `Set<sid>` | Sessions already registered with NanoClaw |
+
+### Database Schema (relevant columns in `chats`)
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `jid` | TEXT PK | `local@web-{sessionId}` |
+| `name` | TEXT | Session display name |
+| `name_updated_at` | INTEGER | UNIX epoch of the last rename |
+| `cwd` | TEXT | Current working directory |
+| `last_message_time` | TEXT | ISO timestamp updated on every message |
+
+---
+
+## Development Workflow
+
+If you are running NanoClaw from source (not via `npx`):
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Build
+npm run build
+
+# 3. Run
+node dist/cli.js [options]
+# or equivalently:
+npx @rozek/nanoclaw [options]
+```
+
+To apply changes and rebuild in one step:
+
+```bash
+npm run build && node dist/cli.js
+```
+
+---
+
+## License
+
+MIT — same as the upstream [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw).