⚔️ Aetheel
A personal AI assistant that lives in your chat — with persistent memory, dual runtimes, auto-failover, and zero cloud dependencies.
Quick Start •
Features •
Commands •
Architecture •
Configuration •
Docs
---
## Quick Start
### One-line install
```bash
curl -fsSL http://10.0.0.59:3051/tanmay/Aetheel/raw/branch/main/install.sh | bash
```
The interactive installer handles everything:
- Checks prerequisites (Python 3.12+, uv)
- Installs dependencies
- Detects or installs AI runtimes (OpenCode / Claude Code)
- Walks you through token setup for Slack, Discord, Telegram
- Installs the `aetheel` shell command
- Sets up a background service (launchd on macOS, systemd on Linux)
### After install
```bash
aetheel start # Start the bot
aetheel stop # Stop the background service
aetheel restart # Restart the service
aetheel status # Check status
aetheel logs # Tail live logs
aetheel setup # Re-run setup wizard
aetheel update # Pull latest + update deps
aetheel doctor # Run diagnostics
aetheel config # Edit config.json
aetheel help # All options
```
### Manual install
```bash
git clone http://10.0.0.59:3051/tanmay/Aetheel.git
cd Aetheel
uv sync # or: pip install -r requirements.txt
cp .env.example .env # edit with your tokens
uv run python main.py # start
```
Everything is config-driven — no flags required. See [Configuration](#configuration).
---
## Features
### 💬 Multi-Channel
| Channel | Connection | Auth | Setup |
|---------|-----------|------|-------|
| Slack | Socket Mode (no public URL) | Bot + App tokens | [docs/slack-setup.md](docs/slack-setup.md) |
| Discord | Gateway (no public URL) | Bot token | [docs/discord-setup.md](docs/discord-setup.md) |
| Telegram | Bot API polling | Bot token | @BotFather |
| WebChat | HTTP + WebSocket on localhost | None (localhost only) | Config: `webchat.enabled: true` |
| Webhooks | HTTP POST endpoints | Bearer token | Config: `webhooks.enabled: true` |
All adapters are config-driven. Set a token in `.env` and the adapter auto-enables — no flags needed.
### 🤖 Dual AI Runtimes with Live Switching
| Runtime | Engine | Providers | Session Continuity |
|---------|--------|-----------|-------------------|
| OpenCode | `opencode` | Anthropic, OpenAI, Google, any | `--continue --session` |
| Claude Code | `claude` | Anthropic | `--continue --session-id` |
Switch engines, models, and providers live from chat — no restart needed:
```
engine claude
model claude-sonnet-4-20250514
engine opencode
model openai/gpt-4o
provider openai
```
### 🔄 Auto-Failover & Usage Tracking
When a rate limit or quota error is detected:
1. You get notified in the channel
2. Aetheel automatically switches to the other engine and retries
3. If failover succeeds, the response is delivered seamlessly
Claude Code returns per-request cost (`cost_usd`), which is tracked and viewable via the `usage` command. Rate limit hits and failover counts are also tracked.
### 🧠 Persistent Memory System
- **Identity files** — `SOUL.md` (personality), `USER.md` (user profile), `MEMORY.md` (long-term notes)
- **Hybrid search** — 0.7 vector + 0.3 BM25 keyword scoring
- **Local embeddings** — fastembed (ONNX, BAAI/bge-small-en-v1.5, 384-dim), zero API calls
- **SQLite storage** — FTS5 full-text search + JSON vector embeddings
- **Session logs** — Conversations auto-saved to `daily/YYYY-MM-DD.md`
- **File watching** — Auto re-indexes when `.md` files change
### ⏰ Scheduler & Action Tags
The AI can trigger actions by including tags in its response:
| Tag | Effect |
|-----|--------|
| `[ACTION:remind\|5\|Drink water!]` | One-shot reminder in 5 minutes |
| `[ACTION:cron\|0 9 * * *\|Good morning!]` | Recurring cron job |
| `[ACTION:spawn\|Research Python 3.14]` | Background subagent task |
Jobs are persisted in SQLite and survive restarts.
### 🔧 More
- **Skills** — Teach the AI domain-specific behavior via `SKILL.md` files
- **Hooks** — Event-driven lifecycle hooks (startup, shutdown, commands)
- **Heartbeat** — Periodic proactive tasks via `HEARTBEAT.md`
- **Subagents** — Background AI tasks with results sent back to the channel
- **MCP Servers** — Extend the agent with external tool servers
- **WebChat** — Browser-based chat UI at `http://localhost:8080`
- **Webhooks** — HTTP endpoints for external systems to trigger the agent
### 🔒 Local-First
- Embeddings run locally (no API calls for memory)
- All data stored in `~/.aetheel/` — your data stays on your machine
- Only the AI runtime makes external API calls
---
## Chat Commands
Type these as regular messages in any channel or DM. No `/` prefix needed.
> In Slack channels, Slack intercepts `/` as native slash commands. Use the prefix-free form (e.g. `engine claude` not `/engine claude`). In DMs and other adapters, both forms work.
### General
| Command | Description |
|---------|-------------|
| `status` | Bot status, engine, model, sessions |
| `help` | All available commands |
| `time` | Server time |
| `sessions` | Active session count |
| `reload` | Reload config and skills |
| `subagents` | List active background tasks |
### Runtime (live, no restart)
| Command | Description |
|---------|-------------|
| `engine` | Show current engine |
| `engine opencode` | Switch to OpenCode |
| `engine claude` | Switch to Claude Code |
| `model` | Show current model |
| `model ` | Switch model |
| `provider` | Show current provider (OpenCode only) |
| `provider ` | Switch provider |
| `usage` | LLM usage stats, costs, rate limits |
### Config
| Command | Description |
|---------|-------------|
| `config` | Config summary |
| `config show` | Full config.json |
| `config set ` | Edit config (e.g. `config set runtime.timeout_seconds 300`) |
### Scheduler
| Command | Description |
|---------|-------------|
| `cron list` | List scheduled jobs |
| `cron remove ` | Remove a job |
See [docs/commands.md](docs/commands.md) for the full reference including terminal commands.
---
## Architecture
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Slack │ │ Discord │ │ Telegram │ │ WebChat │
│ (Socket) │ │ (Gateway) │ │ (Polling) │ │ (WebSocket) │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │ │
└────────────────┴────────────────┴────────────────┘
│
┌───────────┴───────────┐
│ main.py │
│ (ai_handler) │
│ │
│ • Command routing │
│ • Action tag parsing │
│ • Usage tracking │
│ • Auto-failover │
└───┬──────────┬────────┘
│ │
┌─────────┴──┐ ┌───┴──────────┐
│ Memory │ │ AI Runtime │
│ Manager │ │ │
│ │ │ OpenCode ◄──►│ Auto-failover
│ • SOUL.md │ │ Claude ◄──►│
│ • search │ │ │
│ • logs │ │ subprocess │
└────────────┘ └──────────────┘
│
┌─────┴──────┐
│ Scheduler │ Skills, Hooks, Heartbeat,
│ Subagents │ Webhooks, MCP Servers
└────────────┘
```
### Project Structure
```
aetheel/
├── main.py # Entry point, command routing, failover
├── config.py # Config loading (config.json + .env)
├── cli.py # Click CLI (aetheel command)
├── install.sh # Interactive installer + setup wizard
├── adapters/
│ ├── base.py # BaseAdapter + IncomingMessage
│ ├── slack_adapter.py # Slack Socket Mode
│ ├── discord_adapter.py # Discord Gateway
│ ├── telegram_adapter.py # Telegram Bot API
│ └── webchat_adapter.py # Browser WebSocket chat
├── agent/
│ ├── opencode_runtime.py # OpenCode CLI/SDK + rate limit detection
│ ├── claude_runtime.py # Claude Code CLI + usage extraction
│ └── subagent.py # Background subagent manager
├── memory/
│ ├── manager.py # Sync, search, identity files, session logs
│ ├── embeddings.py # Local embeddings (fastembed)
│ ├── hybrid.py # Hybrid search (vector + BM25)
│ ├── schema.py # SQLite schema
│ ├── internal.py # Hashing, chunking, file discovery
│ └── types.py # Config and result types
├── scheduler/
│ ├── scheduler.py # APScheduler with SQLite persistence
│ └── store.py # Job store
├── skills/ # Skill discovery and context injection
├── hooks/ # Lifecycle hook system
├── heartbeat/ # Periodic proactive tasks
├── webhooks/ # HTTP webhook receiver
├── static/
│ └── chat.html # WebChat browser UI
├── docs/
│ ├── commands.md # Full command reference
│ ├── setup.md # Detailed setup guide
│ ├── security-audit.md # Security audit findings
│ ├── configuration.md # Config deep dive
│ ├── memory-system.md # Memory architecture
│ ├── features-guide.md # Feature walkthrough
│ ├── slack-setup.md # Slack app creation guide
│ └── discord-setup.md # Discord bot setup guide
├── tests/ # Test suite
├── .env.example # Secrets template
└── pyproject.toml # Dependencies
```
---
## Configuration
All settings live in `~/.aetheel/config.json`. Secrets (tokens, API keys) live in `.env`.
The install script writes both files during setup. You can also edit them from chat using `config set`.
### Config File
```jsonc
{
"runtime": {
"engine": "opencode", // "opencode" or "claude"
"mode": "cli", // "cli" or "sdk"
"model": null, // e.g. "anthropic/claude-sonnet-4-20250514"
"provider": null, // e.g. "anthropic", "openai", "google"
"timeout_seconds": 120
},
"claude": {
"model": null, // e.g. "claude-sonnet-4-20250514"
"max_turns": 3,
"no_tools": false
},
"slack": { "enabled": true },
"telegram": { "enabled": false },
"discord": { "enabled": false, "listen_channels": [] },
"webchat": { "enabled": false, "port": 8080, "host": "127.0.0.1" },
"webhooks": { "enabled": false, "port": 8090, "token": "" },
"memory": { "workspace": "~/.aetheel/workspace", "db_path": "~/.aetheel/memory.db" },
"heartbeat": { "enabled": true, "default_channel": "slack" },
"hooks": { "enabled": true },
"mcp": { "servers": {} }
}
```
Adapters auto-enable when their token is set in `.env`, even without `enabled: true`.
### Secrets (.env)
```bash
# Slack (required for Slack adapter)
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
# Discord (required for Discord adapter)
DISCORD_BOT_TOKEN=...
# Telegram (required for Telegram adapter)
TELEGRAM_BOT_TOKEN=...
# Anthropic API key (for Claude Code runtime)
ANTHROPIC_API_KEY=sk-ant-...
```
### Environment Variable Overrides
| Variable | Overrides |
|----------|-----------|
| `AETHEEL_ENGINE` | `runtime.engine` |
| `OPENCODE_MODE` | `runtime.mode` |
| `OPENCODE_MODEL` | `runtime.model` |
| `OPENCODE_PROVIDER` | `runtime.provider` |
| `CLAUDE_MODEL` | `claude.model` |
| `CLAUDE_TIMEOUT` | `claude.timeout_seconds` |
| `CLAUDE_MAX_TURNS` | `claude.max_turns` |
| `LOG_LEVEL` | `log_level` |
---
## Memory Files
Auto-created in `~/.aetheel/workspace/` (or personalized during setup):
| File | Purpose |
|------|---------|
| `SOUL.md` | Personality, values, communication style |
| `USER.md` | User preferences, context, background |
| `MEMORY.md` | Long-term notes, facts, things to remember |
All agents share the same identity files — the main agent and any background subagents it spawns all read from the same `SOUL.md`, `USER.md`, and `MEMORY.md`. This is by design: subagents are workers for the same assistant, not separate personalities.
The installer lets you choose a personality preset (default, professional, casual, or custom) and fills in `USER.md` with your name, role, timezone, and preferences interactively.
Edit these files directly anytime — changes are picked up automatically via file watching.
Session logs: `~/.aetheel/workspace/daily/YYYY-MM-DD.md`
---
## Prerequisites
- Python 3.12+ (managed via [uv](https://docs.astral.sh/uv/))
- At least one chat platform token (Slack, Discord, Telegram, or WebChat)
- At least one AI runtime:
- [OpenCode](https://opencode.ai) — `curl -fsSL https://opencode.ai/install | bash`
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — `npm install -g @anthropic-ai/claude-code`
The installer handles all of this interactively.
---
## Development
```bash
# Run full test suite
uv run python test_all.py
# Run pytest
uv run python -m pytest tests/ -v
# Diagnostics
uv run python cli.py doctor
```
---
## Docs
| Document | Description |
|----------|-------------|
| [commands.md](docs/commands.md) | Full command reference (chat + terminal) |
| [setup.md](docs/setup.md) | Detailed setup guide |
| [configuration.md](docs/configuration.md) | Config deep dive |
| [security-audit.md](docs/security-audit.md) | Security audit findings |
| [memory-system.md](docs/memory-system.md) | Memory architecture |
| [features-guide.md](docs/features-guide.md) | Feature walkthrough |
| [slack-setup.md](docs/slack-setup.md) | Slack app creation |
| [discord-setup.md](docs/discord-setup.md) | Discord bot setup |
---
## Inspired By
Built with inspiration from [OpenClaw](https://github.com/nichochar/openclaw) — a TypeScript AI agent framework. Aetheel reimplements the core concepts (memory, hybrid search, session management) in Python with a local-first philosophy.
---
Made with ❤️ and a lot of Claude