AlexClaw 🦇

A BEAM-native personal autonomous AI agent built on Elixir/OTP.

AlexClaw monitors the world (RSS feeds, web sources, GitHub repositories, APIs), accumulates knowledge, executes workflows autonomously on schedule, and communicates with its owner via Telegram. It routes every task to the cheapest available LLM that satisfies the required reasoning tier — including fully local models.

Designed as a single-user personal agent. Not a platform. Not a marketplace. One codebase, fully auditable, running on your infrastructure.

"I didn't plan most of this. I just kept solving the next problem."

Features

Core

• Multi-Model LLM Router — Tier-based routing (light / medium / heavy / local) with priority-based selection. All providers (cloud and local) are stored in PostgreSQL and fully manageable from the admin UI. Tracks daily usage per provider in ETS. Ships with default providers (Gemini, Claude, Ollama, LM Studio) seeded on first boot — add, remove, or reconfigure any provider at runtime.
• Workflow Engine — Define multi-step linear pipelines with conditional branching. Each skill declares its possible outcomes (branches), and the executor routes to different steps based on which branch fires. Execution is sequential — one path per run, no fan-out (a step cannot broadcast to multiple parallel successors). Notify skills pass through their input unchanged, enabling chained delivery to multiple channels in the same pipeline. Per-step resilience controls (circuit breaker, missing skill handling, fallback routing). Zero LLM tokens spent on routing — pure deterministic pattern matching. Full run history with branch path visualization. Export/Import — workflows can be exported as self-contained JSON files (definition, steps, resources) and imported on any instance. Resources are matched by name+URL or created automatically. Filterable workflow list.
• Reasoning Loop — Autonomous plan-execute-evaluate cycle. The LLM decomposes a goal into a multi-step plan, invokes whitelisted skills, evaluates results on a 1-5 rubric, and decides whether to continue, adjust the plan, ask the user, or declare done. Default LLM tier is local (configurable). Deterministic pre-filter handles obvious decisions without an LLM call (0ms). Plan validation rejects malformed steps before execution. Working memory compression every 3 iterations. Proportional time budget scales with plan size. Real-time user intervention: pause, resume, steer, abort, step override. Full audit trail — every prompt, response, skill call, rubric score, and working memory snapshot persisted. Skill outputs embedded to pgvector for future session context. Available from the chat page in Reasoning mode.
• OTP Circuit Breaker — Per-skill circuit breaker using GenServer + ETS. After consecutive failures a skill is temporarily disabled (circuit open), then automatically re-tested after a cooldown. Telegram notifications on state transitions. Dead letter routing: workflow steps can skip, halt, or fallback to an alternative skill when a circuit is open or a skill is missing. Zero external dependencies — pure OTP.

• Multi-Gateway (Telegram + Discord) — Bidirectional communication via Telegram long-polling or Discord bot WebSocket. Command routing is deterministic pattern-matching — no LLM involved in dispatch. Both gateways can run simultaneously; responses route back to the originating transport. The Gateway behaviour allows adding new transports without changing skills or the Dispatcher.
• Runtime Configuration — All settings (API keys, prompts, limits, personas) are stored in PostgreSQL, cached in ETS, and editable at runtime via the admin UI. No restart required for any config change.
• API Resource Discovery — API-type resources are automatically probed on creation. OpenAPI/Swagger specs are discovered at common paths, parsed, and stored in resource metadata. The workflow step editor shows discovered endpoints as a dropdown for pre-filling api_request step config. Manual re-discovery via "Discover" button.
• Persistent Memory with Semantic Search — PostgreSQL + pgvector for knowledge storage. Deduplication by URL. Hybrid search combines vector cosine similarity and keyword matching — vector results are prioritized, keyword results fill gaps for exact matches. Embeddings are generated asynchronously via the LLM router (Gemini gemini-embedding-001, Ollama nomic-embed-text, or any OpenAI-compatible endpoint). 768-dimension vectors with HNSW index. All skills that store knowledge auto-embed in the background.
• Knowledge Base RAG — Separate knowledge_entries table for documentation and reference material, isolated from news/conversation memory. Scraper skills fetch, chunk, and embed documentation from hexdocs.pm, Erlang/OTP source (GitHub), Elixir stdlib source, Learn You Some Erlang, and existing skill code. Chat integrates both Knowledge and Memory search with a context source selector. ~7200 embeddings across 6 knowledge kinds.
• Cron Scheduler — Quantum-based. Jobs defined in config or DB.
• Multi-Node BEAM Clustering — Multiple AlexClaw instances connected via Erlang distribution. Each node runs its own executor independently; nodes exchange workflow outputs via send_to_workflow and receive_from_workflow skills. Auto-discovery, node status monitoring, and per-workflow node assignment from the admin UI. docker-compose_swarm.yml included for local multi-node testing.
• MCP Server — Model Context Protocol server exposes all skills and workflows as MCP tools, and internal data (knowledge, memory, workflows, runs, config) as MCP resources. External AI clients (Claude Code, Cursor, Claude Desktop) can discover and invoke AlexClaw capabilities via the /mcp endpoint. Bearer token auth, policy-based tool restrictions, dynamic tool list refresh via PubSub. Built on anubis_mcp with Streamable HTTP transport.

Skills

Deprecation Notice (v0.3.15): web_browse, web_search, and rss_collector are deprecated and will be removed in v0.4.0. Use the new composable pattern instead: web_fetch → llm_transform, web_search_fetch → llm_transform, rss_fetch → llm_score → llm_transform. See the v0.3.15 release notes for migration examples.

| Skill | Description | |---|---| | web_fetch | Fetch a URL, return extracted text (no LLM) | | web_search_fetch | Search DuckDuckGo + fetch pages, return raw content (no LLM) | | rss_fetch | Fetch RSS feeds, dedup, filter recent, return JSON items (no LLM) | | llm_transform | Run a prompt template through the LLM (workflow glue step) | | llm_score | Batch-score items for relevance via single LLM call | | rss_collector | Fetch + score + notify all-in-one (deprecated, use rss_fetch → llm_score) | | web_search | Search + synthesize (deprecated, use web_search_fetch → llm_transform) | | web_browse | Fetch + summarize (deprecated, use web_fetch → llm_transform) | | research | Deep research with memory context | | conversational | Free-text LLM conversation | | telegram_notify | Send a Telegram message as a workflow step | | discord_notify | Send workflow output to a Discord channel. Configurable channel_id per step — deliver to different channels in the same workflow | | api_request | REST client with API resource discovery — auto-discovers OpenAPI specs, resolves URLs from assigned resources, supports {base_url} interpolation | | github_security_review | Fetch PR/commit diff, run LLM security analysis | | google_calendar | Fetch upcoming Google Calendar events | | google_tasks | Manage Google Tasks lists and items | | db_backup | PostgreSQL backup with gzip compression and weekly rotation to host-mounted path | | shell | Execute whitelisted OS commands for container introspection (2FA-gated) | | web_automation | Browser automation via headless Playwright sidecar (experimental) | | coder | Generate dynamic skills from natural language via local LLM | | send_to_workflow | Send data to a workflow on another BEAM node | | receive_from_workflow | Gate: accepts remote triggers when placed as step 1 | | hexdocs_scraper | Scrape hexdocs.pm docs into knowledge base embeddings (dynamic) | | erlang_docs_scraper | Fetch Erlang/OTP docs from GitHub into knowledge base (dynamic) | | lyse_scraper | Scrape Learn You Some Erlang chapters into knowledge base (dynamic) | | elixir_source_scraper | Fetch Elixir stdlib source from GitHub for pattern learning (dynamic) | | skill_source_indexer | Index existing skill source code into knowledge base (dynamic) |

Dynamic Skill Loading

Load custom skills at runtime — no code changes, no Docker rebuild, no restart. Drop an .ex file into the skills volume (or upload via the admin UI), and it compiles into the running VM immediately.

• Permission sandbox — Dynamic skills declare permissions and interact through SkillAPI only. Undeclared permissions are denied at runtime. Context-aware PolicyEngine evaluates chain depth, capability tokens, and configurable policy rules.
• External skill detection — Skills that fetch external data declare external/0. Dynamic skills are AST-scanned at load time — undeclared HTTP/socket calls are rejected (fail-closed).
• Content sanitization — 7-layer heuristic sanitizer strips prompt injection payloads from external content before LLM ingestion. Detects hidden HTML/CSS, zero-width unicode steganography, known injection patterns (101 from Garak), and imperative tone anomalies. Patterns loaded from JSON at runtime — updatable without recompilation.
• Capability tokens — Macaroon-style HMAC-sig