🦞 Clawdie — Architecture & Implementation Status

NanoClaw v1.1.3 codebase overview • 07.03.2026

1. What Clawdie Is

Clawdie is a WhatsApp AI assistant that routes group messages to Claude Code agents running inside FreeBSD jails. Each registered group gets its own isolated jail environment. The orchestrator (NanoClaw) handles all coordination: message polling, group queuing, agent lifecycle, task scheduling, and inter-process communication.

1.1 System Architecture

1.2 Codebase Structure

2. Tech Stack

3. Implemented Subsystems

3.1 FreeBSD Jail Isolation

Each Claude Code agent runs inside a FreeBSD jail. The orchestrator uses jexec to enter the jail and run the agent-runner. Filesystem mounts are via nullfs (read-only by default, allowlist-controlled via mount-security.ts).

The agent communicates results back to the orchestrator via structured JSON between sentinel markers on stdout:

---NANOCLAW_OUTPUT_START---
{"status": "success", "result": "...", "newSessionId": "session-abc"}
---NANOCLAW_OUTPUT_END---

3.2 Group Queue

src/group-queue.ts enforces two invariants: only one jail runs per group at a time, and a global cap (MAX_CONCURRENT_JAILS) limits simultaneous jails across all groups. Additional behaviours:

• Exponential backoff retry on agent failure (base 5 s, max 5 retries)
• Task priority — enqueued tasks drain before message checks for the same group
• Idle preemption — if a task arrives while the agent is idle, stdin is closed immediately to free the slot
• Graceful shutdown — queue.shutdown(ms) drains active jails before process exit

3.3 Message Loop

src/index.ts polls SQLite every POLL_INTERVAL ms for new messages across registered groups. For each group with messages: checks trigger pattern, pipes to active jail if idle (hot path), otherwise enqueues via GroupQueue. Startup recovery re-queues any messages that arrived while the process was down.

3.4 IPC — Agent ↔ Orchestrator

Agents write JSON files to a watched directory. The IPC watcher processes them atomically with authorization enforcement:

Supported operations: message, schedule_task, pause_task, resume_task, cancel_task, refresh_groups, register_group. Non-main groups are restricted to their own JID and tasks.

3.5 Task Scheduler

Tasks run in their own jail, separate from the group's message-handling jail. Context mode isolated gives a fresh session; group inherits the group's current Claude session ID.

3.6 WhatsApp Channel

QR code pairing, reconnection, message receipt, typing indicators, group metadata sync via @whiskeysockets/baileys. All messages stored to SQLite — the message loop polls the DB, decoupling the channel from the agent lifecycle and surviving reconnects cleanly.

3.7 Skills Engine

Skills are installable packages that modify the NanoClaw codebase via a patch-replay system (skills-engine/). Handles install, update, uninstall, and rebase (re-apply patches after a NanoClaw upstream update).

3.8 tmux-screenshot

Captures the clawdie tmux session to PNG. UUID derived from SHA256 of stripped content — same state always produces same filename (deduplication + self-verification). Features: correct double-width character column calculation, full ANSI color support (basic 16, 256-color, 24-bit truecolor). Output: ai.clawdie.si/screenshots/.

4. Configuration Reference

5. What Remains To Build

5.1 coding-agent TUI Integration

The coding-agent skill package is present but the actual swap of Claude Code for the coding-agent TUI inside the jail is not implemented. Needed: verify it runs on FreeBSD, wire agent-runner to launch it, adapt stdout JSON protocol, test session continuity.

5.2 Stripe Agents

Phase 1: configure Stripe MCP Server with a restricted read-only API key, expose to agents via jail MCP tool list. Gives agents read access to payments and customers without write risk.

5.3 Additional Channels

Skills for Telegram, Discord, Slack, and Gmail are installed but not activated — each requires its own credentials and registering the channel alongside WhatsApp in src/index.ts.