AlexClaw - BEAM-native personal autonomous AI agent

AlexClaw is a single-user autonomous AI agent built on Elixir/OTP. It accumulates knowledge in PostgreSQL, executes workflows on schedule and on demand, and communicates via Telegram. Every task is routed to the cheapest available LLM that satisfies the required reasoning tier — including fully local models via Ollama or LM Studio.

This is a personal agent, not a platform. One operator, one codebase, fully auditable.
Actual version v0.3.3

Core components

Workflow engine — Workflows are composable DAGs stored in PostgreSQL. Each step specifies a skill, config, optional LLM tier/provider overrides, and conditional routes. Skills declare their possible outcomes via a routes/0 callback (e.g. [:on_items, :on_empty, :on_error]) and return a triple tuple {:ok, result, :branch_name} — the executor matches the branch to determine the next step. Steps without routes fall through linearly (backward compatible). The input_from field enables fan-in patterns — a step can pull its input from any earlier step rather than the immediately preceding one. Loop protection via visited set prevents infinite cycles. Steps support on_circuit_open and on_missing_skill policies (halt / skip / fallback) for resilience. A SchedulerSync GenServer keeps Quantum cron jobs in sync with DB-configured schedules at runtime, without restart.

LLM Router — Every LLM call declares a tier (light, medium, heavy, local). The router resolves the enabled provider with the lowest priority value for that tier from PostgreSQL, with ETS caching. Falls back to local if no cloud provider is available. Supports openai_compatible, ollama, gemini, anthropic, and custom provider types. Daily usage limits per provider, tracked in ETS and persisted across restarts. Provider selection can be overridden at three levels (most specific wins): step-level llm_tier/llm_model fields, workflow-level default_provider, or the global tier-based fallback chain.

Memory — PostgreSQL + pgvector knowledge store. Each entry has a kind (fact, summary, news_item, conversation, security_review, etc.), a source, an optional TTL, and a 768-dimension embedding (HNSW index, cosine distance). Embedding generation is async — Memory.store/3 inserts immediately, a TaskSupervisor child generates the vector and updates the row. Hybrid search runs vector similarity and keyword queries in parallel. Falls back to keyword-only when no embedding provider is configured.

Circuit breaker — Per-skill OTP process under a DynamicSupervisor. ETS for lock-free state reads on the hot path, Process.send_after for reset timers. Three consecutive failures open the circuit; Telegram notification on open and recovery. Zero external dependencies.

Config system — All settings live in PostgreSQL, cached in ETS, editable from the admin UI without restart. Sensitive values (API keys, tokens, OAuth secrets) are encrypted at rest with AES-256-GCM; the key is derived from SECRET_KEY_BASE via HKDF-SHA256. Changes broadcast via Phoenix PubSub so all processes pick them up immediately.

Web automator sidecar — Python/Playwright FastAPI service for browser automation. Supports recording sessions (with noVNC for interactive use), replaying saved steps headlessly, and single-shot scrape/screenshot. Called from the WebAutomation skill over HTTP.

Resources — Shared data objects assignable to workflows, stored in PostgreSQL. Types: rss_feed, website, document, api, automation (recorded browser sessions). Skills access assigned resources via args[:resources] in run/1. The feeds management page is a convenience wrapper over resources filtered by type rss_feed.

Admin UI — Phoenix LiveView, fully server-rendered (no JS hooks). 13 pages: dashboard, interactive chat (semantic memory search, pick any LLM provider), workflows, workflow run history (step-level output and duration), skills, scheduler, LLM providers, feeds, resources, memory, DB browser, config, and a real-time log viewer with severity filtering powered by an in-memory ring buffer attached to the Erlang Logger.

Security — Session auth with ETS-based rate limiting on login. Optional TOTP 2FA (per-workflow, not global). HMAC-SHA256 GitHub webhook verification using a CachingBodyReader plug to preserve the raw body for signature checks. Telegram chat_id filtering.

Built-in skills

rss_collector, llm_transform, telegram_notify, research, web_search, web_browse, web_automation, github_security_review, google_calendar, google_tasks, api_request, conversational

New skills implement a single @behaviour AlexClaw.Skill with a run/1 callback. The SkillRegistry discovers them at startup via module introspection. Skills can also be created dynamically at runtime — new skill modules are compiled and hot-loaded into the running BEAM without restart, and become immediately available to workflows and the dispatcher.

Dependencies

Phoenix 1.7, Ecto/Postgrex, pgvector, Req, Quantum, NimbleTOTP, SweetXml, Floki, Jason. No external dependencies for the circuit breaker or config encryption.

License

Apache 2.0

https://github.com/thatsme/AlexClaw