Aetheel/docs/research/nanoclaw-comparison.md

Aetheel vs NanoClaw — Feature Gap Analysis

Deep comparison of Aetheel (Python, multi-channel AI assistant) and NanoClaw (TypeScript, container-isolated personal AI assistant). Focus: what NanoClaw has that Aetheel is missing.

---

Architecture Differences

Aspect	Aetheel	NanoClaw
Language	Python	TypeScript
Agent execution	In-process (shared memory)	Container-isolated (Apple Container / Docker)
Identity model	Shared across all channels (SOUL.md, USER.md, MEMORY.md)	Per-group (each group has its own CLAUDE.md)
Security model	Application-level checks	OS-level container isolation
Config approach	Config-driven (config.json with env.vars + ${VAR})	Code-first (Claude modifies your fork)
Philosophy	Feature-rich framework	Minimal, understandable in 8 minutes

---

Features Aetheel Is Missing

1. Container Isolation (Critical)

NanoClaw runs every agent invocation inside a Linux container (Apple Container on macOS, Docker on Linux). Each container:

• Gets only explicitly mounted directories
• Runs as non-root (uid 1000)
• Is ephemeral (--rm flag, fresh per invocation)
• Cannot access other groups' files or sessions
• Cannot access host filesystem beyond mounts

Aetheel runs everything in-process with no sandboxing. The security audit already flagged path traversal, arbitrary code execution via hooks, and unvalidated action tags as critical issues.

What to build:

• Docker-based agent execution (spawn a container per AI request)
• Mount only the relevant group's workspace directory
• Pass secrets via stdin, not mounted files
• Add a /convert-to-docker skill or built-in Docker mode

---

2. Per-Group Isolation

NanoClaw gives each chat group its own:

• Filesystem folder (groups/{name}/)
• Memory file (CLAUDE.md per group)
• Session history (isolated .claude/ directory)
• IPC namespace (prevents cross-group privilege escalation)
• Container mounts (only own folder + read-only global)

Aetheel shares SOUL.md, USER.md, and MEMORY.md across all channels and conversations. A Slack channel, Discord server, and Telegram group all see the same memory and identity.

What to build:

• Per-channel or per-group workspace directories
• Isolated session storage per group
• A global/ shared memory that all groups can read but only the main channel can write
• Group registration system (like NanoClaw's registerGroup())

---

3. Working Agent Teams / Swarms

NanoClaw has working agent teams today via Claude Code's experimental CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1:

• Lead agent creates teammates using Claude's native TeamCreate / SendMessage tools
• Each teammate runs in its own container
• On Telegram, each agent gets a dedicated bot identity (pool of pre-created bots renamed dynamically via setMyName)
• The lead agent coordinates but doesn't relay every message — users see teammate messages directly
• <internal> tags let agents communicate without spamming the user

Aetheel has the tools in the allowed list (TeamCreate, TeamDelete, SendMessage) but no actual orchestration, no per-agent identity, and no way for teammates to appear as separate entities in chat.

What to build:

• Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 when using Claude runtime
• Bot pool for Telegram/Discord (multiple bot tokens, one per agent role)
• IPC routing that respects sender field to route messages through the right bot
• Per-agent CLAUDE.md / SOUL.md files
• <internal> tag stripping in outbound messages

---

4. Mount Security / Allowlist

NanoClaw has a tamper-proof mount allowlist at ~/.config/nanoclaw/mount-allowlist.json (outside the project root, never mounted into containers):

• Defines which host directories can be mounted
• Default blocked patterns: .ssh, .gnupg, .aws, .env, private_key, etc.
• Symlink resolution before validation (prevents traversal)
• nonMainReadOnly forces read-only for non-main groups
• Per-root allowReadWrite control

Aetheel has no filesystem access control. The AI can read/write anywhere the process has permissions.

What to build:

• External allowlist config (outside workspace, not modifiable by the AI)
• Blocked path patterns for sensitive directories
• Symlink resolution and path validation
• Read-only enforcement for non-primary channels

---

5. IPC-Based Communication

NanoClaw uses file-based IPC for all agent-to-host communication:

• Agents write JSON files to data/ipc/{group}/messages/ and data/ipc/{group}/tasks/
• Host polls IPC directories and processes files
• Per-group IPC namespaces prevent cross-group message injection
• Authorization checks: non-main groups can only send to their own chat, schedule tasks for themselves
• Error files moved to data/ipc/errors/ for debugging

Aetheel uses in-memory action tags parsed from AI response text ([ACTION:remind|...], [ACTION:cron|...]). No authorization, no isolation, no audit trail.

What to build:

• File-based or queue-based IPC for agent communication
• Per-group namespaces with authorization
• Audit trail for all IPC operations
• Error handling with failed message preservation

---

6. Group Queue with Concurrency Control

NanoClaw has a GroupQueue class that manages container execution:

• Max concurrent containers limit (MAX_CONCURRENT_CONTAINERS, default 5)
• Per-group queuing (messages and tasks queue while container is active)
• Follow-up messages sent to active containers via IPC input files
• Idle timeout with _close sentinel to wind down containers
• Exponential backoff retry (5s base, max 5 retries)
• Graceful shutdown (detaches containers, doesn't kill them)
• Task priority over messages in drain order

Aetheel has a simple concurrent limit of 3 subagents but no queuing, no retry logic, no follow-up message support, and no graceful shutdown.

What to build:

• Proper execution queue with configurable concurrency
• Per-channel message queuing when agent is busy
• Follow-up message injection into active sessions
• Exponential backoff retry on failures
• Graceful shutdown that lets active agents finish

---

7. Task Context Modes

NanoClaw scheduled tasks support two context modes:

• group — uses the group's existing session (shared conversation history)
• isolated — fresh session per task run (no prior context)

Aetheel scheduled tasks always run in a fresh context with no option to share the group's conversation history.

What to build:

• context_mode field on scheduled jobs (group vs isolated)
• Session ID passthrough for group mode tasks

---

8. Task Run Logging

NanoClaw logs every task execution:

• task_run_logs table with: task_id, run_at, duration_ms, status, result, error
• last_result summary stored on the task itself
• Tasks auto-complete after once schedule runs

Aetheel's scheduler persists jobs but doesn't log execution history or results.

What to build:

• Task run log table (when it ran, how long, success/error, result summary)
• Queryable task history (task history <id>)

---

9. Streaming Output with Idle Timeout

NanoClaw streams agent output in real-time:

• Container output is parsed as it arrives (sentinel markers for robust parsing)
• Results are forwarded to the user immediately via sendMessage
• Idle timeout (default 30 min) closes the container if no output for too long
• Prevents hanging containers from blocking the queue

Aetheel waits for the full AI response before sending anything back.

What to build:

• Streaming response support (send partial results as they arrive)
• Idle timeout for long-running agent sessions
• Typing indicators while agent is processing

---

10. Skills as Code Transformations

NanoClaw's skills are fundamentally different from Aetheel's:

• Skills are SKILL.md files that teach Claude Code how to modify the codebase
• A deterministic skills engine applies code changes (three-way merge, file additions)
• Skills have state tracking (.nanoclaw/state.yaml), backups, and rollback
• Examples: /add-telegram, /add-discord, /add-gmail, /add-voice-transcription, /convert-to-docker, /add-parallel
• Each skill is a complete guide: pre-flight checks, code changes, setup, verification, troubleshooting

Aetheel's skills are runtime context injections (markdown instructions added to the system prompt when trigger words match). They don't modify code.

What to build:

• Skills engine that can apply code transformations
• State tracking for applied skills
• Rollback support
• Template skills for common integrations

---

11. Voice Message Transcription

NanoClaw has a skill (/add-voice-transcription) that:

• Detects WhatsApp voice notes (audioMessage.ptt === true)
• Downloads audio via Baileys
• Transcribes using OpenAI Whisper API
• Stores transcribed content as [Voice: <text>] in the database
• Configurable provider, fallback message, enable/disable

Aetheel has no voice message handling.

What to build:

• Voice message detection per adapter (Telegram, Discord, Slack all support voice)
• Whisper API integration for transcription
• Transcribed content injection into the conversation

---

12. Gmail / Email Integration

NanoClaw has a skill (/add-gmail) with two modes:

• Tool mode: agent can read/send emails when triggered from chat
• Channel mode: emails trigger the agent, agent replies via email
• GCP OAuth setup guide
• Email polling with deduplication
• Per-thread or per-sender context isolation

Aetheel has no email integration.

What to build:

• Gmail MCP integration (or direct API)
• Email as a channel adapter
• OAuth credential management

---

13. WhatsApp Support

NanoClaw's primary channel is WhatsApp via the Baileys library:

• QR code and pairing code authentication
• Group metadata sync
• Message history storage per registered group
• Bot message filtering (prevents echo loops)

Aetheel supports Slack, Discord, Telegram, and WebChat but not WhatsApp.

What to build:

• WhatsApp adapter using a library like Baileys or the WhatsApp Business API
• QR code authentication flow
• Group registration and metadata sync

---

14. Structured Message Routing

NanoClaw has a clean channel abstraction:

• Channel interface: connect(), sendMessage(), isConnected(), ownsJid(), disconnect(), setTyping?()
• findChannel() routes outbound messages to the right channel by JID prefix (tg:, dc:, WhatsApp JIDs)
• formatOutbound() strips <internal> tags before sending
• XML-escaped message formatting for agent input

Aetheel's adapters work but lack JID-based routing, <internal> tag support, and typing indicators across all adapters.

What to build:

• JID-based message routing (prefix per channel)
• <internal> tag stripping for agent-to-agent communication
• Typing indicators for all adapters
• Unified channel interface with ownsJid() pattern

---

Priority Recommendations

High Priority (Security + Core Gaps)

1. Container isolation for agent execution
2. Fix the 10 critical/high security issues from the security audit
3. Per-group isolation (memory, sessions, filesystem)
4. Mount security allowlist

Medium Priority (Feature Parity)

5. Working agent teams with per-agent identity
6. Group queue with concurrency control and retry
7. Task context modes and run logging
8. Streaming output with idle timeout
9. IPC-based communication with authorization

Lower Priority (Nice to Have)

10. Voice message transcription
11. WhatsApp adapter
12. Gmail/email integration
13. Skills as code transformations
14. Structured message routing with JID prefixes

---

What Aetheel Has That NanoClaw Doesn't

For reference, these are Aetheel strengths to preserve:

• Dual runtime support (OpenCode + Claude Code) with live switching
• Auto-failover on rate limits
• Per-request cost tracking and usage stats
• Local vector search (hybrid: 0.7 vector + 0.3 BM25) with fastembed
• Built-in multi-channel (Slack, Discord, Telegram, WebChat, Webhooks)
• WebChat browser UI
• Heartbeat / proactive task system
• Lifecycle hooks (gateway:startup, command:reload, agent:response, etc.)
• Comprehensive CLI (aetheel start/stop/restart/logs/doctor/config/cron/memory)
• Config-driven setup (no code changes needed for basic customization)
• Self-modification (AI can edit its own config, skills, identity files)
• Hot reload (/reload command)