MonkeyClaw

A secure-by-default personal AI assistant built on the BEAM. OTP-native, fault-tolerant, and distributed by design.

OTP 27+ Elixir 1.17+ Phoenix 1.8 BeamAgent Security-First

Why MonkeyClaw?

The AI assistant product category is proven, but existing solutions have catastrophic security postures. MonkeyClaw delivers the same capabilities with security built into the platform, not patched on top.

🔒

Secure by Default

Default-deny policy, process isolation, no implicit system access. Security comes from the BEAM, not patches.

OTP Supervision

Every agent is a supervised process. Crashes are isolated, recovered, and audited automatically.

🔌

Distributed

Single user, multiple nodes. Run agents across machines with encrypted BEAM distribution — no SSH required.

Extensible

Plug-based extension model for application-level capabilities, plus agent-level MCP, skills, and plugins via BeamAgent.

📋

Multi-Agent

Five AI backend adapters (Claude, Codex, Gemini, OpenCode, Copilot) via BeamAgent, with unified session management.

🔁

Real-Time Streaming

Token-by-token response delivery through the full stack — BeamAgent to LiveView progressive rendering.

🔬

Experiment Engine

Strategy-driven iteration loops with evaluate-decide cycles, mutation scope enforcement, checkpoint rollback, and optional human gates.

🗃

Session History & Recall

SQLite-backed conversation persistence with FTS5 full-text search, temporal and role filtering, and automatic cross-session context injection via the recall extension plug.

🗂

Embedded Persistence

SQLite3 with STRICT mode and WITHOUT ROWID — zero-ops, type-safe storage with clustered UUID lookups, purpose-built for single-user deployments.

🌟

Self-Improving Skills

Reusable procedures extracted from accepted experiments. FTS5-indexed for natural language discovery, effectiveness scoring tracks what works, and an ETS hot cache keeps injection latency low.

🕓

Autonomous Scheduling

Pure OTP scheduling for timed experiment runs — fire once or on recurring intervals. Poll-based GenServer with status lifecycle, run tracking, and configurable bounds.

👤

User Modeling

Privacy-aware observation of user interactions. Extracts topic frequencies and behavioral patterns, then injects personalized context into agent prompts for improved response quality.

📩

Webhook Ingress

Multi-source webhook receiver with 16 built-in sources (GitHub, GitLab, Slack, Discord, Bitbucket, Forgejo, Stripe, Twilio, Linear, Sentry, PagerDuty, Vercel, Netlify, CircleCI, Mattermost) and source-specific signature verification, replay detection, per-endpoint rate limiting, and async agent dispatch. AES-256-GCM encrypted secrets at rest.

🔔

Notifications

Event-driven notification system connecting telemetry to user-facing alerts. Workspace-scoped rules match event patterns with severity thresholds, delivering via in-app PubSub, email, or both. ETS-cached routing, real-time LiveView updates, and a full REST API for programmatic access.

💬

Channel Adapters

Bi-directional messaging with Slack, Discord, Telegram, WhatsApp, and the web UI. Stateless adapter behaviour with platform-specific webhook verification (HMAC-SHA256, Ed25519), inbound parsing, outbound delivery via supervised async tasks, and global notifications across all pages.

🔑

Vault & Secret Management

Encrypted API key and OAuth token storage with @secret:name opaque references — the AI model never sees plaintext. AES-256-GCM encryption at rest, HKDF-derived keys, secret scanning guardrails (14 patterns), and a LiveView management UI.

🤖

Model Registry

Periodic provider model list cache with SQLite persistence and ETS write-through for low-latency reads. GenServer-managed refresh cycles for Anthropic, OpenAI, and Google APIs with graceful degradation on failures.

Architecture

MonkeyClaw is the product layer, BeamAgent is the runtime substrate, and the bridge layers in between translate domain objects into agent operations. Clean separation of concerns, connected through a public Elixir API.

Workflow Layer
MonkeyClaw.Workflows — conversation recipes
Product Layer
MonkeyClaw — assistants · workspaces · experiments · scheduling · user modeling · webhooks · notifications · channels · vault · model registry
Extension Layer
Plug pipelines — hooks · contexts · pipelines
Agent Bridge
Backend behaviour · Session GenServer · Telemetry
Elixir API
beam_agent_ex — sessions · threads · memory · policy
Runtime Substrate
BeamAgent — orchestration · audit · transports · MCP

Documentation

Full API documentation generated with ExDoc.

Browse API Docs