Aetheel/docs/commands.md

Aetheel Commands Reference

All commands work across every adapter (Slack, Discord, Telegram, WebChat).

Chat Commands

Type these as regular messages in any channel or DM. No / prefix needed — just send the word as a message. The / prefix also works in DMs and on platforms that don't intercept it (Discord, Telegram, WebChat).

In Slack channels, Slack intercepts / as a native slash command and blocks it. Use the prefix-free form instead (e.g. engine claude not /engine claude). In Slack DMs with the bot, both forms work.

General

Command	Description
status	Show bot status, engine, model, sessions
help	Show all available commands
time	Current server time
sessions	Active session count + cleanup stale
reload	Reload config.json and skills
subagents	List active background tasks

Runtime Switching (live, no restart needed)

Command	Description
engine	Show current engine (opencode/claude)
engine opencode	Switch to OpenCode runtime
engine claude	Switch to Claude Code runtime
model	Show current model
model <name>	Switch model (e.g. model anthropic/claude-sonnet-4-20250514)
provider	Show current provider (OpenCode only)
provider <name>	Switch provider (e.g. provider anthropic, provider openai)
usage	Show LLM usage stats, costs, and rate limit history

Engine, model, and provider changes take effect immediately and are persisted to config.json so they survive restarts.

Examples

engine claude
model claude-sonnet-4-20250514

engine opencode
model anthropic/claude-sonnet-4-20250514
provider anthropic

model openai/gpt-4o
provider openai

model google/gemini-2.5-pro
provider google

Configuration

Command	Description
config	Show config summary (engine, model, adapters)
config show	Dump full config.json
config set <key> <value>	Edit a config value (dotted notation)

Config Set Examples

config set runtime.timeout_seconds 300
config set claude.max_turns 5
config set webchat.enabled true
config set discord.enabled true
config set webhooks.token my-secret-token
config set heartbeat.silent true

After config set, run reload to apply changes that don't auto-apply (adapter changes require a restart).

Scheduler

Command	Description
cron list	List all scheduled jobs
cron remove <id>	Remove a scheduled job by ID

MCP Servers

Command	Description
mcp list	List configured MCP servers
mcp add <name> <command> [args]	Add a new MCP server
mcp remove <name>	Remove an MCP server

Examples:

mcp add brave-search uvx brave-search-mcp@latest
mcp add filesystem npx @anthropic-ai/mcp-filesystem /home/user/projects
mcp add github uvx github-mcp-server
mcp remove brave-search

Skills

Command	Description
skill list	List all loaded skills
skill show <name>	View a skill's content
skill create <name>	Create a new skill template
skill rename <old> <new>	Rename a skill
skill remove <name>	Remove a skill
skill reload	Reload all skills

You can also manage skills via natural language:

Natural Language	What It Does
"Create a skill for checking weather"	Creates a skill with auto-derived name and triggers
"Rename my-old-skill to weather"	Renames the skill directory and updates SKILL.md

These are handled locally (no AI call needed), so they work even if the AI runtime is down.

AI Chat

Any message that isn't a command is sent to the AI. The AI can also trigger actions by including tags in its response:

AI Action Tag	What It Does
[ACTION:remind|<minutes>|<message>]	Schedule a one-shot reminder
[ACTION:cron|<cron_expr>|<prompt>]	Schedule a recurring cron job
[ACTION:spawn|<task>]	Spawn a background subagent

---

Terminal Commands

After installation, the aetheel command is available in your shell.

Service Management

Command	Description
aetheel start	Start Aetheel in the foreground
aetheel stop	Stop the background service
aetheel restart	Restart the background service
aetheel status	Show install and service status
aetheel logs	Tail the live log file

Setup & Maintenance

Command	Description
aetheel setup	Re-run the interactive setup wizard
aetheel update	Pull latest code + update dependencies
aetheel doctor	Run diagnostics (config, tokens, runtimes)
aetheel config	Open config.json in your $EDITOR

Pass-Through

Any other arguments are passed directly to main.py:

aetheel --test              # Echo mode, no AI
aetheel --claude            # Override: use Claude engine
aetheel --model gpt-4o      # Override: specific model
aetheel --log DEBUG          # Override: debug logging

These flags are optional overrides. All settings come from ~/.aetheel/config.json by default.

---

Config File Reference

All features are controlled by ~/.aetheel/config.json. No flags required.

{
  "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 },
  "webhooks": { "enabled": false, "port": 8090, "token": "" },
  "heartbeat": { "enabled": true },
  "hooks":    { "enabled": true }
}

Adapters auto-enable when their token is set in .env, even if enabled is false in config.

---

Auto-Failover & Rate Limit Handling

When a rate limit or quota error is detected from the active engine:

1. Aetheel notifies you in the channel with the error details
2. Automatically attempts to failover to the other engine (claude → opencode or vice versa)
3. If failover succeeds, the response is delivered and the active engine is switched
4. If failover also fails, both errors are reported

Rate limit detection covers: HTTP 429, "rate limit", "quota exceeded", "too many requests", "usage limit", "credit balance", "overloaded", and similar patterns from both Claude Code and OpenCode.

Use usage to see cumulative stats including rate limit hits and failover count.

Note: Claude Code's --output-format json returns cost_usd per request. OpenCode does not currently expose per-request cost in its CLI output, so cost tracking is only available for the Claude engine.