# ⚔️ 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

```mermaid
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