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.

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-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. All operations require 2FA verification via Telegram/Discord.
• 2FA enforced — Every skill load, unload, and reload requires TOTP verification sent to Telegram/Discord. No exceptions, no bypass. Skill management is Admin UI only.
• Version bump enforcement — Loading a skill that's already loaded with the same version is rejected. Bump version/0 or use reload to force.
• 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.

Permissions

Getting Started

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.

GitHub Security Review

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

Observability

• Health endpoint — GET /health (unauthenticated) returns {"status":"ok","version":"...","db":"connected","mcp":"running"} 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, MCP status and tool count, log severity counts, and knowledge/memory entry counts.

Database Backups

Automated PostgreSQL backups via the db_backup core skill. Backups are gzip-compressed pg_dump files saved to a host-mounted directory — not inside the container filesystem, so they survive container recreation and volume deletion.

• Host bind mount — backups are written to /app/backups inside the container, mapped to a host directory via docker-compose.yml (${BACKUP_DIR:-./backups}:/app/backups). Set BACKUP_DIR in .env to customize the host path (e.g. BACKUP_DIR=D:/Backups/alexclaw on Windows, BACKUP_DIR=/mnt/backups/alexclaw on Linux).
• Mount verification — the skill checks that /app/backups is a real bind mount (via /proc/mounts and device ID comparison). If the directory is on the container's overlay filesystem, the backup is refused with a clear error — preventing false confidence in backups that would be lost on docker-compose down.
• Weekly rotation — keeps the last N backups (configurable via backup.max_files, default 7). Oldest files are automatically deleted.
• Workflow integration — create a workflow with db_backup as a step, add a telegram_notify or discord_notify step for confirmation, and schedule it via cron (e.g. daily at 03:00: 0 3 * * *). Enable backups from Admin > Config (backup.enabled = true).

Security

• Session-based authentication — all routes except /login and /health require an authenticated session
• Two-Factor Authentication (2FA) — TOTP-based via authenticator apps. Setup via Telegram or Discord (/setup 2fa, /confirm 2fa). Mandatory for: skill management (Admin UI), workflows marked Requires 2FA, and shell commands. Cross-channel verification: Admin UI actions verified via Telegram/Discord.
• 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, mcp_restriction), and persistent audit logging
• MCP Bearer token auth — MCP endpoint requires Authorization: Bearer <token> validated against mcp.api_key via constant-time comparison. Policy-based tool restrictions allow blocking specific tools for MCP clients. Sensitive config values are redacted in MCP resource responses
• 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

Architecture

Telegram <──> TelegramGateway ──┐
Discord  <──> DiscordGateway  ──┼──> Router ──> Dispatcher ──> Skills
MCP Client <──> MCP.Server ────┘
                                │
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.

Quick Start

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.

Configuration

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.

Minimum required environment variables

LLM providers (at least one required)

Discord (optional)

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.

LLM Tier System

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.

Per-skill defaults: Each skill has a configurable default tier (e.g. skill.research.tier), set from the admin UI or directly via chat: /research --tier local saves the default for future calls. When a query includes --tier, it overrides the saved default for that single call. Use --tier without a query to save, or with a query to override.

Telegram/Discord Commands

Admin UI

Project Structure

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 (13 pages including Chat)
    plugs/           # RequireAuth, RateLimit, RawBodyReader
priv/repo/
  migrations/        # All DB migrations
  seeds/             # Example workflow seeds

Known Limitations

• 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.
• Forge is pre-alpha. See below.

Forge — Pre-Alpha

Here be dragons. Forge is the self-extending capability engine for AlexClaw. It generates dynamic skills from natural language goals using RAG context from the knowledge base, then automatically compiles, validates, and hot-loads them into the running system. It works, it's dangerous, APIs will change without notice. Use at your own risk.

Code Intelligence Reports

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

Security

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

Contributing

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

License

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