🤖 Alvin Bot — Autonomous AI Agent

Your personal AI agent — on Telegram, WhatsApp, Discord, Slack, Signal, Terminal, and Web.

Alvin Bot is an open-source, MIT-licensed, self-hosted autonomous AI agent that runs on your own machine and answers you on Telegram, Slack, Discord, WhatsApp, Signal, a terminal TUI, and a web dashboard. It is built on the official Claude Agent SDK and runs a provider-agnostic engine that also drives OpenAI, Groq, Google Gemini, NVIDIA NIM, OpenRouter, and Ollama, with automatic failover after two consecutive provider failures and a heartbeat health check every five minutes. Unlike most personal AI agents, it ships a zero-config indexed memory store: with no embedding API key it falls back to a built-in SQLite FTS5 keyword index, so recall works out of the box. It dispatches detached sub-agents as independent claude -p subprocesses that keep running and deliver their result even if the parent conversation is aborted. It is local-first and telemetry-free — prompts and responses are never logged off-machine, secrets live in a chmod-0600 .env, and shell execution is allowlisted by default.

What's new — v5.61 (June 2026): Background follow-ups are now bullet-proof. When Alvin says "I'll do X once the sub-agent is done", that follow-up fires reliably under every condition — including after a bot restart, a sleep, or a result that lands while the bot was briefly down — so you never have to ask "is it done yet?". New: a follow-up can wait for a whole group of sub-agents ("research X, Y and Z, then compare all three") and fire exactly once when the last finishes, with every result together. Works the same on the Claude path, the Code CLI bridge, and Gemini / Groq / local models. (v5.60 brought the full agent experience + the Claude-Code voice to non-Claude providers — see the changelog.) Full changelog →

✨ Features

🧠 Intelligence

• Multi-model engine — Claude Agent SDK · OpenAI · Groq · NVIDIA NIM · Gemini · OpenRouter · Ollama · Codex CLI · any OpenAI-compatible API
• Automatic fallback + heartbeat monitor — checks providers every 5 min (token-free for API-key providers — the free models endpoint, not a paid completion), auto-failover after 2 failures, auto-recovery; reorder priority via Telegram /fallback, Web UI, or API
• Adjustable thinking depth & answer length — /effort low to /effort max; /verbosity short|medium|full applies on every input path (text, voice, photos, documents, web)
• Pluggable memory backends (v4.22) — Gemini · OpenAI · Ollama · FTS5 keyword fallback. Auto-detection picks the best available. Indexed search across MEMORY.md, daily logs, project files, hub memory, asset index. Override via EMBEDDINGS_PROVIDER.
• Smart system-prompt injection (v4.22) — once SQLite is populated, stops bulk-injecting MEMORY.md and surfaces only the chunks relevant to the user's current message. Cuts ~25 k tokens per turn for typical setups. MEMORY_INJECT_MODE=auto|legacy|sqlite to override.
• Layered memory (L0–L3) — identity.md + preferences.md always plain-text · project memories on topic match · daily logs / curated knowledge via semantic or keyword search
• Persistent sessions — Claude SDK resume tokens, conversation history, language, effort survive bot restarts
• Multi-session workspaces — parallel context-isolated sessions per Slack channel or /workspace switch, each with its own cwd, purpose, persona. Memory + skills stay globally shared. How-to ↓
• Detached sub-agents — alvin_dispatch_agent MCP tool spawns independent claude -p subprocesses that survive parent aborts. Results deliver as separate messages; /subagents list shows live per-task health (dead process, stalled output) and /subagents cancel stops them safely. Optional cost routing sends light tasks to a cheaper model (SUBAGENT_AUTO_ROUTE). Works identically on Telegram / Slack / Discord / WhatsApp.
• Smart tool discovery — scans your system at startup; typical install surfaces 30–70 tools depending on what's locally available
• Skill system — 14 SKILL.md files (see Skills ↓) auto-activate based on message context
• Self-awareness + auto-language — knows it IS the AI · detects EN/DE/ES/FR and adapts; learns preference over time

💬 Multi-Platform

• Telegram — streaming, inline keyboards, voice, photos, documents
• Slack — Socket Mode via @slack/bolt, DMs + @mentions, file attachments, assistant.threads.setStatus typing. One channel = one isolated workspace.
• WhatsApp — via WhatsApp Web; self-chat as AI notepad, group whitelist with per-contact access, full media. Owner approval gate routes to Telegram (DM / Discord / Signal fallback) before the bot replies.
• Discord — server bot with mention/reply detection and slash commands
• Signal — via signal-cli REST API, voice transcription
• Terminal — rich TUI with ANSI colors + streaming (alvin-bot tui)
• Web UI — full dashboard, chat, settings, file manager, terminal, workspace overview

🔧 Capabilities

• Tool layer — Shell · files · Python · git · email · PDF · media · vision · screenshots · system control. Universal tool use across any provider that supports function calling; text-only fallback for those that don't.
• 6 built-in plugins — weather · finance · notes · calendar · email · smarthome
• MCP client — connect any Model Context Protocol server
• Cron — AI-driven scheduled tasks ("check my email every morning"), @daily/@hourly shorthand, shell jobs run without blocking the bot, and a self-healing scheduler that restarts itself in-process if it ever wedges
• Voice — STT via Groq Whisper, TTS via Edge TTS or ElevenLabs
• Vision + image generation — photo / document analysis · Gemini / DALL·E generation with API key
• Browser — 4-tier strategy: WebFetch · stealth Playwright · CDP with persistent profile · agent-browser CLI (Tier-1.5, opt-in)

🖥️ Web Dashboard

• WebSocket streaming chat · model switcher · platform & provider setup · file manager · memory editor · session browser · in-browser terminal · maintenance + health · workspace cards with cost aggregation

⚖️ How Alvin Bot compares

Alvin Bot sits in the same category as Hermes Agent (Nous Research) and OpenClaw — self-hosted, open-source personal AI agents that live on your machine and reach you on the chat apps you already use. They optimize for different things. This table is intended to be fair: where Hermes or OpenClaw is the better tool, it says so.

Use the right tool for the job

• Use Alvin Bot when you want one resilient, self-healing agent on your own box that keeps working when a provider rate-limits or fails, gives you indexed memory without buying an embedding API key, ships safe-by-default execution sandboxing, and is built directly on the official Claude Agent SDK — and you mainly live in Telegram / Slack / Discord / WhatsApp / Signal.
• Use Hermes Agent when you want a research-grade self-improving agent, need it to act as an MCP server for Claude Desktop / Cursor / VS Code, want 200+ model choice or many execution backends, and value a large community.
• Use OpenClaw when you want the widest messaging reach (25–50+ channels) plus native mobile apps and voice activation, fully transparent plain-file memory you can git-track, and the largest ecosystem.

A longer head-to-head with FAQ and decision guide: Alvin Bot vs Hermes vs OpenClaw.

🚀 Quick Start

Brand-new machine? One line is all you need — even with nothing installed (no Homebrew, no Xcode tools, no Node, no admin password):

curl -fsSL https://unpkg.com/alvin-bot/install.sh | bash

It reuses an existing Node if you have one, otherwise fetches a self-contained Node into your home folder, installs Alvin into a user-owned location (never sudo, nothing system-wide), and launches the setup wizard.

Already have Node 18+? The classic three commands work too:

npm install -g alvin-bot
alvin-bot setup
alvin-bot start

Either way, the setup wizard validates everything:

• ✅ Lets you pick your AI provider and tests the key
• ✅ Verifies your Telegram bot token
• ✅ Confirms the setup works before you start

You'll need: a Telegram bot token (@BotFather) · your Telegram user ID (@userinfobot). Node.js 18+ (nodejs.org) is auto-installed by the one-line script if missing.

WhatsApp is optional. Telegram, Slack, Discord, terminal and the web UI work out of the box. The WhatsApp connector is an opt-in add-on (it needs a couple of extra packages) — enable it any time from the Web UI (Platforms → Install Dependencies); the bot shows you the exact one-line command when you first try to use it.

Native build note: Alvin Bot uses better-sqlite3 for indexed memory. Prebuilt binaries are included for common macOS and Linux environments so most installs need nothing extra. If your platform doesn't have a prebuilt binary and the optional native compilation is skipped, the bot still runs — semantic memory falls back gracefully to keyword search. A C++ toolchain (Xcode Command Line Tools on macOS, build-essential on Ubuntu) and Python 3 are only needed if you hit a build-from-source fallback.

Free AI providers available — no credit card needed. Privacy-first? Pick the 🔒 Offline — Gemma 4 E4B option in setup for a fully local LLM via Ollama (macOS/Linux: automated install; Windows: manual).

🔐 A note on permission prompts

The first time Alvin reaches for a new tool — a shell command, a file read, a web fetch — you may see a permission prompt from the underlying agent runtime asking whether to allow it. Those prompts come from Alvin himself, not from a third party. Approving one expands what he can do for you autonomously; denying keeps the scope narrow. The more you allow, the more capable and hands-off he becomes — you stay in control either way, and you can always revoke a permission later.

macOS only — one extra step under launchd. If you install Alvin as a background service (alvin-bot launchd install), macOS won't be able to show you those permission dialogs interactively anymore. To let the bot and anything it spawns (Codex CLI, file-reading skills) actually read your files, grant Full Disk Access to node once: System Settings → Privacy & Security → Full Disk Access → + → add /opt/homebrew/Cellar/node/<version>/bin/node (find the exact path with readlink -f "$(which node)"). alvin-bot launchd install and alvin-bot doctor will both detect and remind you with the exact path. After brew upgrade node you'll need to re-grant, because TCC binds to the versioned Cellar path. The printable macOS Setup Guide PDF covers this end-to-end.

📘 First-time setup walkthroughs

Step-by-step printable PDF guides:

Both guides cover: Node.js install · Telegram bot creation · first-time setup · foreground test · background service · offline Gemma 4 mode · troubleshooting. ~15 min end-to-end for a first-time user.

macOS: use launchd instead of pm2 (recommended)

If you're on macOS and using Claude Code (Max subscription) as your provider, run the bot as a LaunchAgent — it inherits the GUI login session so the macOS Keychain stays unlocked and the Claude OAuth token just works without any manual security unlock-keychain dance:

alvin-bot launchd install    # writes ~/Library/LaunchAgents/com.alvinbot.app.plist and starts the agent
alvin-bot launchd status     # show PID + recent stdout/stderr logs
alvin-bot launchd uninstall  # unload + remove the plist

Pm2 still works and remains the default on Linux/Windows — but on macOS with Claude Code, launchd is the only path that reliably keeps Keychain access over restarts.

📖 Handbook

For a full walkthrough of everything Alvin Bot can do — providers, sub-agents, cron jobs, plugins, MCP, security audit, web UI — read docs/HANDBOOK.md.

AI Providers

*Claude SDK requires a Claude Max subscription ($20/mo) or Anthropic API access. The setup wizard checks this automatically.

Alternative Installation

curl -fsSL https://cdn.jsdelivr.net/npm/alvin-bot/install.sh | bash

git clone https://github.com/alvbln/Alvin-Bot.git
cd Alvin-Bot
cp .env.example .env    # Edit with your tokens
docker compose up -d

git clone https://github.com/alvbln/Alvin-Bot.git
cd Alvin-Bot
npm install
npm run build
node bin/cli.js setup   # Interactive wizard
npm run dev             # Start in dev mode

npm install -g pm2
pm2 start ecosystem.config.cjs
pm2 save && pm2 startup

Troubleshooting

alvin-bot doctor        # Check configuration & validate connections

If your AI provider isn't working, run doctor — it tests the actual API connection and shows exactly what's wrong.

📋 Commands

🏗️ Architecture

  Telegram   Slack   WhatsApp   Discord   Signal   Web UI · TUI · CLI
      └─────────┴─────────┴────┬────┴─────────┴───────────┘
                               ▼
              Workspace Resolver  (per-channel cwd + persona)
                               ▼
                 Engine  (routing · fallback · heartbeat)
        ┌──────────────────────┼───────────────────────────┐
        ▼                      ▼                            ▼
   Claude SDK         OpenAI · Groq · Gemini ·      Ollama · Codex CLI ·
                      NVIDIA · OpenRouter           OpenAI-compatible
        │
        ├─ reads ▶  Memory Layer
        │              ├─ L0 / L1 — identity.md · preferences.md (always plain-text)
        │              └─ SQLite store — provider auto-detect (Gemini · OpenAI · Ollama · FTS5)
        │
        └─ dispatches ▶  Detached sub-agents  (independent `claude -p`, survive parent abort)

Rendered as plain text so it displays identically on npm and GitHub (npm's README renderer does not support Mermaid diagrams).

Provider matrix

Universal tool use — Alvin gives full agent powers to any provider that supports function calling. Shell · files · Python · web work everywhere; providers without tool calls degrade cleanly to text-only chat.

Project layout

src/
├── index.ts                 entry point
├── engine.ts                multi-model query engine
├── handlers/                message + command handlers
├── platforms/               Telegram · Slack · WhatsApp · Discord · Signal
├── providers/               Claude SDK · OpenAI-compat · Ollama · Codex CLI
├── services/
│   ├── embeddings/          v4.22 pluggable provider facade (Gemini/OpenAI/Ollama/FTS5)
│   ├── memory*.ts           layered memory (L0-L3) + inject-mode resolver
│   ├── workspaces.ts        per-channel cwd + persona registry
│   ├── alvin-dispatch.ts    detached sub-agent orchestration
│   ├── browser-manager.ts   4-tier browser strategy
│   └── …                    cron · voice · skills · MCP · hooks · …
├── tui/                     terminal chat UI
└── web/                     dashboard server + APIs
web/public/                  zero-build HTML/CSS/JS UI
plugins/                     6 built-in plugins (hot-reload)
skills/                      14 SKILL.md files (hot-reload)
bin/cli.js                   CLI entry point
electron/                    Electron wrapper for the .dmg build

🧭 Multi-Session Workspaces (v4.12.0)

Run multiple parallel Alvin sessions on the same bot — one per project, context-isolated, memory shared. Think Claude Coworker, but on your own machine with your own tools. Each workspace has its own working directory, purpose, and optional persona. Sub-agents spawned in one workspace stay in that workspace. Memory, skills, and the knowledge base are globally shared across all of them.

Why you'd want this

Without workspaces, Alvin has one big blob of context. If you ask about one project's deployment right after debugging a completely unrelated service, Claude pollutes one context with the other. Workspaces solve this: Slack channel = session, or on Telegram, /workspace my-project = session. Each one has its own Claude SDK resume token, history, and current project CLAUDE.md loaded via its working directory.

How it works

1. Drop a markdown file into ~/.alvin-bot/workspaces/<name>.md with YAML frontmatter.
2. Alvin hot-reloads the workspace registry (no restart needed — same pattern as skills).
3. On Slack, workspaces resolve by explicit channel ID first, then by channel name match (#my-project → workspaces/my-project.md, case-insensitive).
4. On Telegram, run /workspace <name> to switch — next message uses the new persona and cwd.
5. Nothing configured? Alvin falls back to the "default" workspace exactly like pre-v4.12 — no breaking changes.

Example workspace file

Create ~/.alvin-bot/workspaces/my-project.md:

---
purpose: my-project website dev
cwd: ~/Projects/my-project
emoji: "🏢"
color: "#6366f1"
channels: ["C01ABCDEF"]
---
You are focused on the my-project website. Stack: React + Express +
Drizzle + MySQL. Production VPS at your-vps.example.com, deploy via rsync.
Prefer concise, directly actionable answers about features, deployment,
and Stripe integration.

The cwd auto-loads the project-specific CLAUDE.md via Claude SDK's settingSources: ["user", "project"], so each workspace inherits its project's conventions automatically. channels is optional — omit it to match by filename.

Slack setup (5 minutes)

1. Download the setup guide + manifest from the latest release:
   • slack-setup.md — step-by-step instructions
   • slack-manifest.json — copy-paste ready Slack App manifest
2. Create a Slack App from the manifest at https://api.slack.com/apps → Create New App → From an app manifest
3. Enable Socket Mode, generate an App-Level Token (starts with xapp-)
4. Install the app to your workspace, copy the Bot User OAuth Token (starts with xoxb-)
5. Add both to ~/.alvin-bot/.env:

   SLACK_APP_TOKEN=xapp-1-...
   SLACK_BOT_TOKEN=xoxb-...
   SLACK_ALLOWED_USERS=U01ABCDEF      # optional, comma-separated

6. Restart Alvin. You should see 💬 Slack connected (Alvin @ YourWorkspace) in the log.
7. Invite Alvin to channels with /invite @Alvin. DMs work without an invite.

Telegram /workspace commands

Workspace selection is per Telegram user, persisted across bot restarts via ~/.alvin-bot/state/sessions.json (v2 envelope format, backwards compatible with v4.11).

Web UI

The dashboard has a dedicated 🧭 Workspaces tab (Data section in the sidebar). Each workspace shows as a color-coded card with emoji, purpose, cwd, mapped channels, session count, message count, and cumulative cost. Useful for spotting which project is burning the most tokens.

Or query directly:

curl -s http://localhost:3100/api/workspaces | jq

Architecture guarantees

• Memory is global. Facts Alvin learns in one workspace are visible in every other workspace via the shared MEMORY.md and embeddings index. Per-workspace memory layer is on the v4.13 roadmap.
• Sub-agents are per-session. Each workspace can dispatch its own detached sub-agents via alvin_dispatch_agent — results come back to the originating channel on any platform (Telegram, Slack, Discord, WhatsApp), visible in /subagents list (v4.13.0+ dispatch, v4.14.0 cross-platform, v4.14.1 unified list view).
• Session state survives restart. Claude SDK resume tokens, conversation history, language, effort, and workspaceName all persist via session-persistence.ts (v4.11.0).
• Backwards compatible. If you don't create any workspace files, everything behaves exactly like v4.11. Upgrade is a no-op.

⚙️ Configuration

Environment Variables

# Required
BOT_TOKEN=<Telegram Bot Token>
ALLOWED_USERS=<comma-separated Telegram user IDs>

# AI Providers (at least one needed)
# Claude SDK uses CLI auth — no key needed
GROQ_API_KEY=<key>              # Groq (voice + fast models)
NVIDIA_API_KEY=<key>            # NVIDIA NIM models
GOOGLE_API_KEY=<key>            # Gemini + image generation
OPENAI_API_KEY=<key>            # OpenAI models
OPENROUTER_API_KEY=<key>        # OpenRouter (100+ models)

# Provider Selection
PRIMARY_PROVIDER=claude-sdk     # Primary AI provider
FALLBACK_PROVIDERS=nvidia-kimi-k2.5,nvidia-llama-3.3-70b

# Memory backend (v4.22+) — auto-detects based on what keys you have.
# Set to override the default priority: gemini → openai → ollama → fts5.
# fts5 is the zero-config keyword fallback — no key needed, works for everyone.
EMBEDDINGS_PROVIDER=auto                  # auto | gemini | openai | ollama | fts5
OLLAMA_EMBEDDING_MODEL=nomic-embed-text   # only used for ollama provider
MEMORY_INJECT_MODE=auto                   # auto | legacy | sqlite (see CHANGELOG v4.22)

# Optional Platforms
WHATSAPP_ENABLED=true           # Enable WhatsApp (needs Chrome)
DISCORD_TOKEN=<token>           # Enable Discord
SIGNAL_API_URL=<url>            # Signal REST API URL
SIGNAL_NUMBER=<number>          # Signal phone number
SLACK_BOT_TOKEN=xoxb-...        # Slack Bot User OAuth Token (Socket Mode)
SLACK_APP_TOKEN=xapp-1-...      # Slack App-Level Token (connections:write scope)
SLACK_ALLOWED_USERS=U01...      # Optional: comma-separated Slack user IDs allowlist

# Multi-Session (v4.12.0)
SESSION_MODE=per-channel        # per-user (default) | per-channel | per-channel-peer
                                # per-channel gives each Slack channel / group its own isolated session

# Optional
WORKING_DIR=~                   # Default working directory (used when no workspace is resolved)
MAX_BUDGET_USD=5.0              # Cost limit per session
WEB_PORT=3100                   # Web UI port
WEB_PASSWORD=<password>         # Web UI auth (optional)
CHROME_PATH=/path/to/chrome     # Custom Chrome path (for WhatsApp)
MEMORY_EXTRACTION_DISABLED=1    # Opt out of v4.11.0 auto-fact-extraction in compaction

Custom Models

Add any OpenAI-compatible model via docs/custom-models.json:

[
  {
    "key": "my-local-llama",
    "name": "Local Llama 3",
    "model": "llama-3",
    "baseUrl": "http://localhost:11434/v1",
    "apiKeyEnv": "OLLAMA_API_KEY",
    "supportsVision": false,
    "supportsStreaming": true
  }
]

Personality

Edit SOUL.md to customize the bot's personality. Changes apply on /reload or bot restart.

WhatsApp Setup

WhatsApp uses whatsapp-web.js — the bot runs as your own WhatsApp account (not a separate business account). Chrome/Chromium is required.

1. Enable WhatsApp

Set WHATSAPP_ENABLED=true in .env (or toggle via Web UI → Platforms → WhatsApp). Restart the bot.

2. Scan QR Code

On first start, a QR code appears in the terminal (and in the Web UI). Scan it with WhatsApp on your phone (Settings → Linked Devices → Link a Device). The session persists across restarts.

3. Chat Modes

All toggles are also available in the Web UI (Platforms → WhatsApp). Changes apply instantly — no restart needed.

4. Group Whitelist

Groups must be explicitly enabled. In the Web UI → Platforms → WhatsApp → Group Management:

• Enable a group to let the bot listen
• Allowed Contacts — Select who can trigger the bot (empty = everyone)
• @ Mention Required — Bot only responds when mentioned (voice/media bypass this)
• Process Media — Allow photos, documents, audio, video
• Approval Required — Owner must approve each message via Telegram before the bot responds. Group members see nothing — completely transparent.

Note: Your own messages in groups are never processed (you ARE the bot on WhatsApp). The bot only responds to other participants. In self-chat, your messages are always processed normally.

5. Approval Flow (when enabled per group)

1. Someone writes in a whitelisted group
2. You get a Telegram notification with the message preview + ✅ Approve / ❌ Deny buttons
3. Approve → bot processes and responds in WhatsApp. Deny → silently dropped.
4. Fallback channels if Telegram is unavailable: WhatsApp self-chat → Discord → Signal
5. Unapproved messages expire after 30 minutes.

🔌 Plugins

Built-in plugins in plugins/:

Plugins are auto-loaded at startup. Create your own by adding a directory with an index.js exporting a PluginDefinition.

🎯 Skills

Skills are markdown files in skills/ that auto-activate when the user's message matches their trigger keywords. The skill body gets injected into the system prompt, giving the agent specialized expertise on demand. 14 ship built-in:

Drop your own <name>/SKILL.md into ~/.alvin-bot/skills/ for hot-reload. List active skills via /skills or alvin-bot skills.

🛠️ CLI

Core lifecycle

alvin-bot setup           # Interactive setup wizard (Telegram + AI provider + tools)
alvin-bot start           # Start the bot in background (launchd on macOS, pm2 elsewhere)
alvin-bot start -f        # Start in foreground (for debugging)
alvin-bot stop            # Stop the running bot
alvin-bot status          # Show version + LaunchAgent / pm2 state (offline)
alvin-bot doctor          # Health check — config, provider, memory, permissions
alvin-bot update          # Pull latest from npm (or git if running from source)
alvin-bot version         # Show version

Interactive chat

alvin-bot tui             # Terminal chat UI with streaming + ANSI colors ✨
alvin-bot chat            # Alias for tui
alvin-bot tui --lang de   # Force German UI

AI provider management (since 4.24.0)

Switch between Claude SDK / Codex CLI / Groq / Gemini / OpenAI / OpenRouter / NVIDIA NIM / offline Gemma 4 without re-running the full setup wizard. The switch command runs the same install + auth flow the wizard uses (CLI install + OAuth login for claude-sdk / codex-cli, API-key prompt + live validation for the rest), then does a byte-preserving merge of ~/.alvin-bot/.env — the previous provider's API key is parked, not deleted, so rollback is one un-comment away.

alvin-bot provider list                # Show all providers + per-provider install/key status
alvin-bot provider show                # Detailed info on the currently configured provider
alvin-bot provider switch <key>        # Switch (interactive setup + .env merge + bot restart)
alvin-bot provider doctor              # Validate current provider's auth against its API

<key> accepts canonical slugs or short aliases: claude, codex, gemini, nvidia, gpt, gemma.

Optional tools — install / update (since 4.23.0)

A curated set of universally useful CLIs that unlock specific skills. Bootstrap tools (yt-dlp, ffmpeg, and wacli if WhatsApp is enabled) are auto-installed/updated by setup and update; the rest you opt into through the menu.

alvin-bot tools list                   # Show installed / missing optional tools
alvin-bot tools install                # Interactive menu — pick which to install

macOS permissions wizard (since 5.1.0)

macOS' TCC framework refuses to let any app grant Full Disk Access / Automation / Accessibility programmatically — only the user can flip those switches. The wizard makes the toggling experience painless: it detects every permission's current state, opens the exact right Settings pane for each missing one, waits for you to toggle (polling every 2 s for up to 60 s per permission), verifies, and moves on. Bundles sudo-password storage in the same upfront flow.

alvin-bot permissions status           # Quick status: all 4 permissions + current state
alvin-bot permissions wizard           # Interactive guided setup, one-and-done
alvin-bot permissions open <id>        # Open one Settings pane (full-disk-access / automation / accessibility)
alvin-bot perms                        # alias for permissions

LaunchAgent (macOS only)

alvin-bot launchd install              # Write ~/Library/LaunchAgents/com.alvinbot.app.plist + load
                                       # (Also installs the dead-man-switch companion plist since 4.26.0)
alvin-bot launchd status               # Show PID + recent stdout/stderr from the LaunchAgent
alvin-bot launchd uninstall            # Unload + remove both plists

Browser automation (bot-managed Chromium)

alvin-bot browser start                # Launch Chromium with CDP, persistent profile
alvin-bot browser start headful        # Same, visible (for login flows)
alvin-bot browser goto <url>           # Open URL, return JSON metadata
alvin-bot browser shot <url> [file]    # Screenshot → ~/.alvin-bot/browser/screenshots/
alvin-bot browser eval <url> "<js>"    # Run JS in page context
alvin-bot browser tabs                 # List open tabs
alvin-bot browser status               # PID + CDP endpoint
alvin-bot browser stop                 # Quit Chromium
alvin-bot browser doctor               # Diagnose Chromium / Playwright setup

Maintenance & introspection

alvin-bot audit                        # Security health check — permissions, secrets, config
alvin-bot search "<query>"             # Search assets, memories, and skills index

Environment-variable opt-outs (Self-Preservation features since 4.26.0 / 5.0.0)

Granular opt-out for the resilience subsystems — everything is enabled by default:

ALVIN_DISABLE_SELF_PRESERVATION=true   # Kill ALL Phase-1 + Phase-2 features below
ALVIN_DISABLE_PREFLIGHT=true           # Skip startup sanity check (Telegram, provider, SQLite, disk)
ALVIN_DISABLE_CRITICAL_NOTIFY=true     # Skip cross-channel alerts (Telegram + macOS notif + file flag)
ALVIN_DISABLE_DEAD_MAN=true            # Skip the zombie-detection heartbeat writer
ALVIN_DISABLE_AUTO_DIAGNOSTIC=true     # Skip forensic-bundle writing on crash
ALVIN_DISABLE_SELF_DIAGNOSIS=true      # Skip AI analysis of forensic bundles at startup
ALVIN_DISABLE_TRENDS=true              # Skip daily trend snapshots + AI anomaly detection
ALVIN_DEADMAN_THRESHOLD_SEC=600        # Dead-man's-switch staleness threshold (default 10 min)
ALVIN_TRENDS_INTERVAL_HOURS=24         # Trend-snapshot cadence (default 24 h)
ALVIN_TRENDS_AI_AFTER_DAYS=7           # Days of history before AI anomaly detection kicks in

🗺️ Roadmap

Per-version details: see CHANGELOG.md. The roadmap is a forward-looking summary, not a changelog.

✅ Recently shipped

🏛️ Foundations (built before v4.10)

Multi-model provider abstraction with fallback chains · plugin & skill ecosystems with hot-reload · multi-platform adapters (Telegram, WhatsApp, Discord, Signal, Slack) · Web UI with i18n + command palette · native macOS .dmg via Electron · Docker Compose · npm distribution · MCP client + custom tools · universal tool use across providers · full media pipeline (audio · video · photo · voice).

🎯 On the radar

Pull requests welcome — see CONTRIBUTING.md.

🔒 Security

⚠️ Important: Alvin has full shell + filesystem access

Alvin Bot is an autonomous AI agent built on the Claude Agent SDK with shell, filesystem, and network access to the machine it runs on. This is by design — it's the point of the project. But it means:

• Treat the bot like sudo access — only install it on machines where you'd trust Claude Code to run without supervision.
• Never expose the Web UI (port 3100) to the internet without HTTPS, rate limiting, and a strong WEB_PASSWORD. It binds to localhost by default.
• On multi-user systems, verify ~/.alvin-bot/.env is chmod 600 (v4.12.2+ enforces this automatically on startup).
• ALLOWED_USERS is your first line of defense — v4.12.2+ refuses to start if it's empty and Telegram is enabled.

Read the full threat model and hardening guide: docs/security.md

Access control

• User whitelist — Only ALLOWED_USERS can interact with the bot (hard-enforced at startup since v4.12.2)
• WhatsApp group approval — Per-group participant whitelist + owner approval gate via Telegram (with WhatsApp DM / Discord / Signal fallback). Group members never see the approval process.
• Slack allowlist — SLACK_ALLOWED_USERS restricts who can DM or @mention the bot in Slack
• DM pairing — Optional 6-digit code flow for new users via owner approval (AUTH_MODE=pairing)

Execution hardening

• EXEC_SECURITY=allowlist (default) — Shell commands must match a whitelist of safe binaries and cannot contain shell metacharacters (;, |, &, `, $(...), redirects). Rejected by v4.12.2's exec-guard metachar filter.
• Cron shell jobs go through the same exec-guard (v4.12.2+) — cron is no longer a bypass vector.
• Sub-agent toolset presets — spawn sub-agents with toolset: "readonly" or "research" to restrict what they can do, regardless of the parent's privileges.
• Timing-safe webhook auth — POST /api/webhook uses crypto.timingSafeEqual (v4.12.2+) to prevent timing side-channel token extraction.

Data hardening

• Self-hosted — Your data stays on your machine. No cloud sync, no external logging of prompts or responses.
• No telemetry — Zero tracking, zero analytics, zero phone-home.
• File permissions — .env, sessions.json, memory logs, cron jobs, and all sensitive state files are chmod 0o600 on every write and repaired at startup (v4.12.2+).
• Owner protection — Owner account cannot be deleted via UI.
• Encrypted sudo credentials — If you enable sudo exec, passwords are stored encrypted with an XOR key in a separate file, both chmod 0o600.

Known limitations (documented honestly)

• Prompt injection cannot be reliably filtered — we document this as a capability tradeoff rather than pretending to solve it. See docs/security.md for the full discussion.
• Not yet hardened for public-internet deployment — current scope is "on your own machine". VPS deployment works but requires additional reverse-proxy + TLS + rate-limit setup that we don't automate.
• Electron Desktop build has known CVEs (Phase 18 roadmap). The primary distribution is npm global install, not Desktop — if you don't use the Desktop wrapper, you're not affected.

📄 License

MIT — See LICENSE.

🤝 Contributing

Issues and PRs welcome! Please read the existing code style before contributing.

git clone https://github.com/alvbln/Alvin-Bot.git
cd alvin-bot
npm install
npm run dev    # Development with hot reload