Aetheel/docs/comparison.md

⚔️ Aetheel vs. Inspiration Repos — Comparison & Missing Features

A detailed comparison of Aetheel with Nanobot, NanoClaw, OpenClaw, and PicoClaw — highlighting what's different, what's missing, and what can be added.

---

Feature Comparison Matrix

Feature	Aetheel	Nanobot	NanoClaw	OpenClaw	PicoClaw
Language	Python	Python	TypeScript	TypeScript	Go
Channels	Slack only	9 channels	WhatsApp only	15+ channels	5 channels
LLM Runtime	OpenCode / Claude Code (subprocess)	LiteLLM (multi-provider)	Claude Agent SDK	Pi Agent (custom RPC)	Go-native agent
Memory	Hybrid (vector + BM25)	Simple file-based	Per-group CLAUDE.md	Workspace files	MEMORY.md + sessions
Config	.env file	config.json	Code changes (no config)	JSON5 config	config.json
Skills	❌ None	✅ Bundled + custom	✅ Code skills (transform)	✅ Bundled + managed + workspace	✅ Custom skills
Scheduled Tasks	⚠️ Action tags (remind only)	✅ Full cron system	✅ Task scheduler	✅ Cron + webhooks + Gmail	✅ Cron + heartbeat
Security	❌ No sandbox	⚠️ Workspace restriction	✅ Container isolation	✅ Docker sandbox + pairing	✅ Workspace sandbox
MCP Support	❌ No	✅ Yes	❌ No	❌ No	❌ No
Web Search	❌ No	✅ Brave Search	✅ Via Claude tools	✅ Browser control	✅ Brave + DuckDuckGo
Voice	❌ No	✅ Via Groq Whisper	❌ No	✅ Voice Wake + Talk Mode	✅ Via Groq Whisper
Browser Control	❌ No	❌ No	❌ No	✅ Full CDP control	❌ No
Companion Apps	❌ No	❌ No	❌ No	✅ macOS + iOS + Android	❌ No
Session Management	✅ Thread-based (Slack)	✅ Session-based	✅ Per-group isolated	✅ Full sessions + agent-to-agent	✅ Session-based
Docker Support	❌ No	✅ Yes	❌ (uses Apple Container)	✅ Full compose setup	✅ Yes
Install Script	✅ Yes	✅ pip/uv install	✅ Claude guides setup	✅ npm + wizard	✅ Binary / make
Identity Files	✅ SOUL.md, USER.md, MEMORY.md	✅ AGENTS.md, SOUL.md, USER.md, etc.	✅ CLAUDE.md per group	✅ AGENTS.md, SOUL.md, USER.md, TOOLS.md	✅ Full set (AGENTS, SOUL, IDENTITY, USER, TOOLS)
Subagents	❌ No	✅ Spawn subagent	✅ Agent Swarms	✅ sessions_send / sessions_spawn	✅ Spawn subagent
Heartbeat/Proactive	❌ No	✅ Heartbeat	❌ No	✅ Cron + wakeups	✅ HEARTBEAT.md
Multi-provider	⚠️ Via OpenCode/Claude	✅ 12+ providers	❌ Claude only	✅ Multi-model + failover	✅ 7+ providers
WebChat	❌ No	❌ No	❌ No	✅ Built-in WebChat	❌ No

---

What Aetheel Does Well

✅ Strengths

1. Advanced Memory System — Aetheel has the most sophisticated memory system with hybrid search (0.7 vector + 0.3 BM25), local embeddings via fastembed, and SQLite FTS5. None of the other repos have this level of memory sophistication.

2. Local-First Embeddings — Zero API calls for memory search. Uses ONNX-based local model (BAAI/bge-small-en-v1.5).

3. Dual Runtime Support — Clean abstraction allowing switching between OpenCode and Claude Code with the same AgentResponse interface.

4. Thread Isolation in Slack — Each Slack thread gets its own AI session, providing natural conversation isolation.

5. Action Tags — Inline [ACTION:remind|minutes|message] tags are elegant for in-response scheduling.

6. File Watching — Memory auto-reindexes when .md files are edited.

---

What Aetheel Is Missing

🔴 Critical Gaps (High Priority)

1. Multi-Channel Support

Current: Slack only All others: Multiple channels (3-15+)

Aetheel is locked to Slack. Adding at least Telegram and Discord would significantly increase usability. All four inspiration repos treat multi-channel as essential.

Recommendation: Follow Nanobot's pattern — each channel is a module in channels/ with a common interface. Start with Telegram (easiest — just a token).

2. Skills System

Current: None Others: All have skills/plugins

Aetheel has no way to extend agent capabilities beyond its hardcoded memory and runtime setup. A skills system would allow:

• Bundled skills (GitHub, weather, web search)
• User-created skills in workspace
• Community-contributed skills

Recommendation: Create a skills/ directory in the workspace. Skills are markdown files (SKILL.md) that get injected into the agent's context.

3. Scheduled Tasks (Cron)

Current: Only [ACTION:remind] (one-time, simple) Others: Full cron systems with persistent storage

The action tag system is clever but limited. A proper cron system would support:

• Recurring cron expressions (0 9 * * *)
• Interval-based scheduling
• Persistent job storage
• CLI management

Recommendation: Add a cron/ module with SQLite-backed job storage and an APScheduler-based execution engine.

4. Security Sandbox

Current: No sandboxing Others: Container isolation (NanoClaw), workspace restriction (PicoClaw), Docker sandbox (OpenClaw)

The AI runtime has unrestricted system access. At minimum, workspace-level restrictions should be added.

Recommendation: Follow PicoClaw's approach — restrict tool access to workspace directory by default. Block dangerous shell commands.

---

🟡 Important Gaps (Medium Priority)

5. Config File System (JSON instead of .env)

Current: .env file with environment variables Others: JSON/JSON5 config files

A structured config file is more flexible and easier to manage than flat env vars. It can hold nested structures for channels, providers, tools, etc.

Recommendation: Switch to ~/.aetheel/config.json with a schema validator. Keep .env for secrets only.

6. Web Search Tool

Current: No web search Others: Brave Search, DuckDuckGo, or full browser control

The agent can't search the web. This is a significant limitation for a personal assistant.

Recommendation: Add Brave Search API integration (free tier: 2000 queries/month) with DuckDuckGo as fallback.

7. Subagent / Spawn Capability

Current: No subagents Others: All have spawn/subagent systems

For long-running tasks, the main agent should be able to spawn background sub-tasks that work independently and report back.

Recommendation: Add a spawn tool that creates a background thread/process running a separate agent session.

8. Heartbeat / Proactive System

Current: No proactive capabilities Others: Nanobot and PicoClaw have heartbeat systems

The agent only responds to messages. A heartbeat system would allow periodic check-ins, proactive notifications, and scheduled intelligence.

Recommendation: Add HEARTBEAT.md file + periodic timer that triggers agent with heartbeat tasks.

9. CLI Interface

Current: Only python main.py with flags Others: Full CLI with subcommands (nanobot agent, picoclaw cron, etc.)

Recommendation: Add a CLI using click or argparse with subcommands: aetheel chat, aetheel status, aetheel cron, etc.

10. Tool System

Current: No explicit tool system (AI handles everything via runtime) Others: Shell exec, file R/W, web search, spawn, message, etc.

Aetheel delegates all tool use to the AI runtime (OpenCode/Claude Code). While this works, having explicit tools gives more control and allows sandboxing.

Recommendation: Define a tool interface and implement core tools (file ops, shell, web search) that run through the aetheel process with sandboxing.

---

🟢 Nice-to-Have (Lower Priority)

11. MCP Server Support

Only Nanobot supports MCP. Would allow connecting external tool servers.

12. Multi-Provider Support

Currently relies on OpenCode/Claude Code for provider handling. Direct multi-provider support (like Nanobot's 12+ providers via LiteLLM) would add flexibility.

13. Docker / Container Support

No Docker compose or containerized deployment option.

14. Agent-to-Agent Communication

OpenClaw's sessions_send allows agents to message each other. Useful for multi-agent workflows.

15. Gateway Architecture

Moving from a direct Slack adapter to a gateway pattern would make adding channels much easier.

16. Onboarding Wizard

OpenClaw's onboard --install-daemon provides a guided setup. Aetheel's install script is good but could be more interactive.

17. Voice Support

Voice Wake / Talk Mode (OpenClaw) or Whisper transcription (Nanobot, PicoClaw).

18. WebChat Interface

A browser-based chat UI connected to the gateway.

19. TOOLS.md File

A TOOLS.md file describing available tools to the agent, used by PicoClaw and OpenClaw.

20. Self-Modification

From additions.txt: "edit its own files and config as well as add skills" — the agent should be able to modify its own configuration and add new skills.

---

Architecture Comparison

graph LR
    subgraph Aetheel["⚔️ Aetheel (Current)"]
        A_SLACK["Slack\n(only channel)"]
        A_MAIN["main.py"]
        A_MEM["Memory\n(hybrid search)"]
        A_RT["OpenCode / Claude\n(subprocess)"]
    end

    subgraph Target["🎯 Target Architecture"]
        T_CHAN["Multi-Channel\nGateway"]
        T_CORE["Core Agent\n+ Tool System"]
        T_MEM["Memory\n(hybrid search)"]
        T_SK["Skills"]
        T_CRON["Cron"]
        T_PROV["Multi-Provider"]
        T_SEC["Security\nSandbox"]
    end

    A_SLACK --> A_MAIN
    A_MAIN --> A_MEM
    A_MAIN --> A_RT

    T_CHAN --> T_CORE
    T_CORE --> T_MEM
    T_CORE --> T_SK
    T_CORE --> T_CRON
    T_CORE --> T_PROV
    T_CORE --> T_SEC

---

Prioritized Roadmap Suggestion

Based on the analysis, here's a suggested implementation order:

Phase 1: Foundation (Essentials)

1. Config system — Switch from .env to JSON config
2. Skills system — skills/ directory with SKILL.md loading
3. Tool system — Core tools (shell, file, web search) with sandbox
4. Security sandbox — Workspace-restricted tool execution

Phase 2: Channels & Scheduling

5. Channel abstraction — Extract adapter interface from Slack adapter
6. Telegram channel — First new channel
7. Cron system — Full scheduled task management
8. CLI — Proper CLI with subcommands

Phase 3: Advanced Features

9. Heartbeat — Proactive agent capabilities
10. Subagents — Spawn background tasks
11. Discord channel — Second new channel
12. Web search — Brave Search + DuckDuckGo

Phase 4: Polish

13. Self-modification — Agent can edit config and add skills
14. Docker support — Dockerfile + compose
15. MCP support — External tool servers
16. WebChat — Browser-based chat UI