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."

• 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.
• 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.
• 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.

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.
• Capability tokens — Macaroon-style HMAC-signed tokens attenuate permissions through the call chain. Workflow steps get scoped tokens; cross-skill invocation further restricts.
• Process isolation — Dynamic skills execute in spawned processes via SafeExecutor, isolating auth state from the caller.
• Namespace enforcement — Module must be AlexClaw.Skills.Dynamic.*
• Integrity verification — SHA256 checksum stored on load, verified on boot. Tampered files are skipped with a Telegram alert.
• Persistence — Dynamic skills survive container restarts (DB + Docker volume)
• Admin UI — Upload, reload, and unload skills from the Skills page. Core and dynamic skills are shown separately.
• Telegram commands — /skill load, /skill unload, /skill reload, /skill create, /skill list
• Cross-skill invocation — Dynamic skills can call other skills (core or dynamic) through SkillAPI.run_skill/3
• Conditional branching — Dynamic skills can declare routes/0 (e.g. [:on_results, :on_empty, :on_error]) and return triple tuples {:ok, result, :branch_name} for workflow routing. Routes are persisted in the database on load and cleaned up on unload — same behavior as core skills.

See test/fixtures/skills/skill_template.ex for a fully documented template with the complete SkillAPI reference. Dynamic skill examples (RSS with full article fetching, NVD CVE Monitor, Research, GitHub Review, Web Search, Web Browse) are available in the same directory.

AlexClaw can review pull requests and commits for security issues:

• Run as a workflow step with per-workflow repo, token, and security focus
• Trigger manually via Telegram: /github pr owner/repo 42
• GitHub webhook endpoint available (/webhooks/github) with HMAC-SHA256 verification
• Diff truncation at 24KB — works with local models
• Structured output: RISK LEVEL, FINDINGS, SUMMARY, RECOMMENDATION

• Health endpoint — GET /health (unauthenticated) returns {"status":"ok","version":"...","db":"connected"} for load balancers and Docker healthchecks. Returns HTTP 503 when the database is unreachable.
• Metrics endpoint — GET /metrics (authenticated) returns a JSON payload with system stats (uptime, memory, BEAM processes), LLM provider usage, workflow run counts, skill and circuit breaker states, log severity counts, and knowledge/memory entry counts.

• Session-based authentication — all routes except /login and /health require an authenticated session
• Two-Factor Authentication (2FA) — TOTP-based via authenticator apps. Setup and confirmation via Telegram (/setup 2fa, /confirm 2fa)
• Built-in login rate limiting — ETS-based, configurable max attempts and block duration, adjustable at runtime without restart
• HMAC-SHA256 webhook verification — GitHub webhook endpoint uses Plug.Crypto.secure_compare for timing-safe signature validation
• Encryption at rest — API keys and tokens are AES-256-GCM encrypted in PostgreSQL, decrypted transparently at runtime
• Sensitive key masking — API keys and tokens show partial values in the admin UI
• Agent authorization layer — Context-aware PolicyEngine with HMAC capability tokens, chain-depth enforcement, process isolation for dynamic skills, configurable policy rules (rate_limit, time_window, chain_restriction, permission_override), and persistent audit logging
• Shell command security — 5-layer defense: disabled by default, 2FA gate, whitelist with word-boundary check, blocklist for shell metacharacters, no shell interpretation (System.cmd/3 with args as list), configurable timeout + output truncation

Telegram <──> TelegramGateway ──┐ Discord <──> DiscordGateway ──┼──> Router ──> Dispatcher ──> Skills │ Admin UI (Chat) ──────> SkillSupervisor ──> Dynamic Skills (DynamicSupervisor) │ ┌──────────────┼──────────────┐ RSS Research NVD CVE Skill Skill Monitor │ LLM Router (Gemini / Anthropic / Ollama / LM Studio) │ ┌───────────┴───────────┐ Memory Config (pgvector + embeddings) (DB + ETS + PubSub) ↑ semantic search ↑ GitHub Webhook ──> WebhookController ──> GitHubSecurityReview Scheduler (Quantum) ──> Workflows.Executor ──┬──> CircuitBreaker ──> Skills ──> Branch Router Phoenix LiveView Admin ──> all of the above └──> Fallback / Skip / Halt └──> Next Step 

Every skill runs as an isolated OTP process. Crashes are contained and supervised. The circuit breaker wraps each skill transparently — skills have zero awareness of it. The Dispatcher is deterministic pattern-matching — no LLM token cost for routing.

See ALEXCLAW_ARCHITECTURE.md for the full design document.

git clone https://github.com/thatsme/AlexClaw.git cd AlexClaw cp .env.example .env # Edit .env — set DATABASE_PASSWORD, SECRET_KEY_BASE, ADMIN_PASSWORD, # TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, and at least one LLM API key docker compose up -d

Open http://localhost:5001 and log in with your ADMIN_PASSWORD. Send /ping to your Telegram bot to verify connectivity.

For detailed setup instructions, Telegram bot setup, and local model configuration, see INSTALLATION.md.

All configuration is managed at runtime through the admin UI (/config). On first boot, values are seeded from environment variables. After that, changes are made in the UI — no restart needed.

All other settings (GitHub tokens, webhook secrets, LLM limits, prompts, skill config) are managed at runtime through the Config UI after first boot.

See .env.example for the full list of bootstrap variables.

All providers live in the database and can be added, removed, or reconfigured from the admin UI. The defaults above are seeded on first boot. The router selects by priority within each tier (lower priority number = preferred), tracks daily usage, and falls back to the next available provider. A fully local deployment with no API keys is supported — enable a local provider and all tiers will fall back to it.

lib/ alex_claw/ config/ # Runtime config (DB + ETS + PubSub broadcast) knowledge/ # Knowledge base entry schema (pgvector) llm/ # LLM router, usage tracker, provider schema memory/ # Memory entry schema auth/ # Authorization layer (PolicyEngine, CapabilityToken, SafeExecutor, AuditLog) skills/ # Core skill modules, SkillAPI, DynamicSkill schema, CircuitBreaker workflows/ # Executor, scheduler sync, SkillRegistry (GenServer+ETS), step/run schemas dispatcher.ex # Deterministic message routing gateway.ex # Telegram bot identity.ex # Agent persona and system prompts llm.ex # Multi-model router memory.ex # Knowledge store rate_limiter.ex # ETS-based login rate limiting scheduler.ex # Quantum cron scheduler alex_claw_web/ controllers/ # Auth, database backup, GitHub webhook live/admin_live/ # LiveView admin pages (12 pages including Chat) plugs/ # RequireAuth, RateLimit, RawBodyReader priv/repo/ migrations/ # All DB migrations seeds/ # Example workflow seeds 

• Semantic search requires an embedding provider. Vector search works when at least one embedding-capable provider is configured (Gemini, Ollama, or OpenAI-compatible). Without one, memory falls back to keyword search. Configure via embedding.provider and embedding.model in the admin UI.
• Single-user only. There is no multi-user access control. The authentication model assumes one trusted operator.
• Sensitive config encrypted at rest. API keys and tokens are AES-256-GCM encrypted in PostgreSQL using SECRET_KEY_BASE as key material. Changing SECRET_KEY_BASE requires re-entering all API keys. See SECURITY.md for details.
• Web Automator is experimental. The browser automation sidecar (web_automation skill) is under heavy development. APIs, config format, and recording workflow may change without notice.

AST-level analysis reports generated by Giulia — heatmap zones, change risk, blast radius, coupling analysis, dead code, and architecture health.

See SECURITY.md for the full security policy and deployment hardening guidance.

See CONTRIBUTING.md for contribution guidelines and CLA.md for the Contributor License Agreement.

Copyright 2026 Alessio Battistutta — Licensed under the Apache License, Version 2.0. See LICENSE for details.