🤖 Alvin Bot — Autonomous AI Agent

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

Alvin Bot is a 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.118.0 (September 2026): Every provider answer now says which level it is talking about. /provider and /model state whether they mean the globally active provider or the lane you are standing in, so a lane pin and a global setting can no longer be mistaken for each other. Slash-command suggestions survive a failed fetch instead of going quiet until reload, opening the dashboard no longer queues up behind its own requests, and reading over loopback has its own rate-limit budget. No capability removed.

v5.91.0 (August 2026): A workspace file that grows without bound no longer taxes every message. Notes kept in a workspace CLAUDE.md are read into every turn; a file grown past 400 KB was measured at roughly 280.000 tokens for a one-word answer. Dated records are now moved to sibling files on demand, rules stay resident, and nothing is ever lost — the rewrite is checked line by line and abandoned if even one line would go missing. Full changelog →

v5.90 (August 2026): Ollama's cloud models now work as a provider. Ollama Pro serves frontier models through the same local port as your downloaded ones; the bot used to declare them missing (they never appear in the local catalogue) and route them through the scaffold built for small local models, which returned an empty answer. Both are fixed, local models keep their behaviour unchanged. Also: the test suite no longer depends on whether an Ollama daemon happens to be running on the machine. Full changelog →

v5.89 (August 2026): Running the bot on a server in Docker now takes one command. alvin-bot docker init writes a Dockerfile, a compose file and a .env template into a directory you choose; docker compose up -d does the rest. The image is built from the published npm package rather than a repository checkout, so there is nothing to clone and nothing to keep in sync. Chromium is included, data lives in a named volume that survives a full recreate, and the Web UI is bound to loopback by default. Also fixed: notes, calendar and smart-home data were stored inside the installed package, where a global install cannot write them and the next npm update would erase them — they now live in the data directory. Full changelog →

v5.88 (August 2026): Lanes can now be created from the browser and pointed at a workspace. Opening a parallel workstream meant switching to Telegram, and binding one to a project context meant a command the Web UI never mentioned. The Lanes view now creates lanes, assigns their workspace from the column header, and can add a workspace itself — name, purpose, working directory, emoji, colour. Changing a lane's workspace later is allowed and says beforehand what it costs: the column keeps its messages while the model loses the thread, plus, for a workspace that shares lane memory, that this lane's daily logs become readable by the other lanes there. A working directory is now stored exactly as entered or refused, never silently normalised into a different one. Full changelog →

v5.87 (August 2026): The bot can now run an adversarial build loop in the background. /gauntlet [light|medium|heavy] <instruction> hands a task to a detached worker that implements it test-first, then sets independent critic agents on the result — correctness, regression, and at heavy a mutation critic that writes changes which keep every assertion intact yet break the behaviour, so tests that only look thorough are exposed. Only real defects trigger another round; cosmetic findings are reported, not iterated on. The chat stays free while it runs, and /subagents cancel stops it. Full changelog →

v5.86 (August 2026): Lane columns can now be reset, renamed and cleared out from the browser. The Lanes view could show parallel workstreams but not manage them. It now has per-lane reset, rename and delete; columns order by last activity so a lane you just watched finish stays put; the header reports tokens rather than dollars; every message carries a date; a badge shows how many sub-agents a lane is running; and files can be dragged straight into a column, streamed to disk under a size cap instead of held in memory. Three fixes as well: answers no longer disappear from a column after finishing, the view reconciles itself after a dropped connection instead of needing a reload, and a finished sub-agent's result is no longer painted as if you had typed it. Full changelog →

v5.85 (August 2026): The bot now recovers from a stuck Telegram connection without restarting itself. Its in-process repair for stuck polling used to be cut off a fraction of a second before it would have worked — the health check judged a freshly restarted polling loop by its predecessor's last success, with a grace period exactly as long as one poll request. Polling health is now judged against each loop's own start time, and the grace period is derived from the real poll timeout instead of coincidentally matching it. A reproduction against a real polling stack went from zero successful recoveries out of seventeen to fourteen out of fifteen; a genuinely stuck connection still escalates to a full restart as before. Full changelog →

v5.84 (August 2026): The bot now makes sure it comes back after restarting itself. Its last-resort self-repair used to be a plain exit, trusting the operating system to notice and relaunch it — if it wasn't actually watching, the bot could stay down indefinitely. On macOS it now hands off to a small helper that waits for the old process to disappear and explicitly tells the service manager to start it again, and the message you get says which route was actually taken. Never two bots at once: the hand-off only acts once the old process is confirmed gone. Also: the bot now checks that its own outside safety-net watcher is still ticking, and tells you once if it has gone quiet. Full changelog →

v5.83 (August 2026): Background agents now work from voice, photo, document and video messages, not just text. Those four message types — and the web chat — were quietly falling back to a temporary in-session helper that dies the moment the turn ends; all of them now dispatch a real, detached agent that survives it. Also: an empty answer used to cost up to ten minutes while a stuck automatic retry sat silent — it now starts clean and reports back in seconds if it fails, though that turn still needs to be sent again. 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, live Lanes view (v5.82)

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

| Dimension | Alvin Bot | Hermes Agent | OpenClaw | |---|---|---|---| | License / hosting | Proprietary · self-hosted · local-first · zero telemetry | MIT · self-hosted · 7 execution backends | Open-source · self-hosted · bring-your-own-key | | Model providers | Claude Agent SDK + OpenAI · Groq · Gemini · NVIDIA NIM · OpenRouter · Ollama, with automatic failover after 2 provider failures + a 5-min heartbeat monitor | 200+ models | Bring-your-own model / key | | Sub-agents | Detached claude -p subprocesses that survive a parent abort; readonly/research toolset presets | Isolated subagents for parallel workstreams | Not a primary focus | | Browser automation | 4-tier escalation: WebFetch → stealth Playwright → persistent-profile CDP → agent-browser CLI | Built-in browse / vision tools | Via tools | | Platforms | Telegram · Slack · Discord · WhatsApp · Signal · terminal TUI · Web (7) | 20+ platforms from one gateway | 25–50+ platforms · native mobile apps · voice activation | | Memory | Layered L0–L3; SQLite embeddings with a zero-config FTS5 keyword fallback (works with no API key); smart prompt-injection trims ~25 k tokens/turn | SQLite + full-text search · agent-curated · Honcho user profiling | Transparent plain Markdown/YAML files you can grep and git-track | | Extensibility | Hot-reload skills + 6 plugins · self-modifying skills · hooks · MCP client | 40+ built-in tools · autonomous self-improving skill loop | Skills as files · very large ecosystem | | MCP | MCP client (connect any MCP server) | MCP client and hermes mcp serve (acts as an MCP server for Claude Desktop / Cursor / VS Code) | Tool integrations | | Self-healing | Startup preflight · dead-man's-switch heartbeat · crash forensic bundles · AI self-diagnosis · crash-loop brake · trend anomaly detection | Stable in practice; self-improving | Frequent updates can break running instances | | Security defaults | Exec allowlist + shell-metachar filter on by default · DM pairing · timing-safe webhook auth · 0600 file perms enforced · alvin-bot audit CLI · honestly documented threat model | Standard | Standard | | Maturity / community | Small, focused, single-maintainer; modest public adoption | Large community, Nous Research team | Large community + team, Nvidia NemoClaw fork |

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

📘 First-time setup walkthrough

| Platform | Guide | |---|---| | 🪟 Windows (WSL + Task Scheduler for 24/7) | Online guide |

Covers: Node.js install · Telegram bot creation · first-time setup · foreground test · background service · offline Gemma 4 mode · troubleshooting.

🔐 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 macOS setup walkthrough covers this end-to-end.

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

| Provider | Cost | Best for | |----------|------|----------| | Groq | Free | Getting started fast | | Google Gemini | Free | Image understanding, embeddings | | NVIDIA NIM | Free | Tool use, 150+ models | | OpenAI | Paid | GPT-4o quality | | OpenRouter | Paid | 100+ models marketplace | | Claude SDK | Paid* | Full agent with tool use |

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

Alternative Installation

The one-liner from Quick Start, served from a second CDN if the first is blocked:

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

Bootstraps Node if missing (self-contained, no sudo), installs Alvin into a user-owned location, and runs the setup wizard automatically.

| Platform | Download | Architecture | |----------|----------|-------------| | macOS | Coming soon | Apple Silicon (M1+) | | Windows | Coming soon | x64 | | Linux | Coming soon | x64 |

The desktop app auto-starts the bot and provides a system tray icon with quick controls.

npm install -g alvin-bot
mkdir -p /opt/alvin-bot && cd /opt/alvin-bot
alvin-bot docker init      # writes Dockerfile, docker-compose.yml and .env here
# edit .env — BOT_TOKEN, ALLOWED_USERS, one AI provider
docker compose up -d

The image is built from the published npm package, so there is no repository to clone. Chromium is included, the Web UI is bound to loopback (reach it over an SSH tunnel), and everything the bot writes lives in a named volume that survives upgrades.

Claude does not work in a container — the Claude SDK provider needs an interactive CLI login. Use Groq, Gemini, OpenAI or a local Ollama.

Full guide: docs/install/docker.md

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

| Command | Description | |---------|-------------| | /help | Show all commands | | /start | Session status overview | | /new | Fresh conversation (reset context) | | /model | Switch AI model (inline keyboard) | | /effort <low\|medium\|high\|max> | Set thinking depth | | /voice | Toggle voice replies | | /imagine <prompt> | Generate images | | /web <query> | Search the web | | /remind <time> <text> | Set reminders (e.g., /remind 30m Call mom) | | /cron | Manage scheduled tasks | | /recall <query> | Search memory | | /remember <text> | Save to memory | | /export | Export conversation | | /dir <path> | Change working directory | | /workspaces | List all configured workspaces (v4.12.0) | | /workspace [name] | Show or switch the active workspace — /workspace default resets (v4.12.0) | | /status | Current session & cost info | | /setup | Configure API keys & platforms | | /system <prompt> | Set custom system prompt | | /fallback | View & reorder provider fallback chain | | /skills | List available skills & their triggers | | /lang <de\|en\|auto> | Set or auto-detect response language | | /cancel | Abort running request | | /reload | Hot-reload personality (SOUL.md) |

🏗️ 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

| Provider | Tool use | Streaming | Vision | Auth | |---|---|---|---|---| | Claude SDK (Agent) | ✅ native (Bash, Read, Write, Web, MCP) | ✅ | ✅ | Claude CLI OAuth | | OpenAI · Groq · Gemini · NVIDIA NIM · OpenRouter | ✅ universal tool use | ✅ | varies | API key | | Ollama (local) | ✅ via tool-bridge | ✅ | varies | none | | Codex CLI | ✅ subprocess | ✅ | — | Codex CLI auth | | Any OpenAI-compatible | ⚡ auto-detect | ✅ | varies | API key |

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.

Sharing memory between lanes of one workspace (v5.65.0, opt-in): add shareLaneMemory: true to the frontmatter and every lane bound to this workspace can recall its sibling lanes' conversational notes — plus a freshly opened lane starts with a short briefing of what its siblings did recently. Without the flag, lanes stay fully isolated (the default). Main's conversation notes stay private to main either way.

Slack setup (5 minutes)

1. Create a Slack App at https://api.slack.com/apps → Create New App → From scratch
2. Enable Socket Mode, generate an App-Level Token (starts with xapp-)
3. Install the app to your workspace, copy the Bot User OAuth Token (starts with xoxb-)
4. Add both to ~/.alvin-bot/.env:

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

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

Telegram /workspace commands

| Command | Effect | |---|---| | /workspaces | List all configured workspaces with emojis and purposes (active one marked ✅) | | /workspace | Show the currently active workspace (inside a lane: that lane's own binding) | | /workspace <name> | Switch to <name> — next message uses its persona and cwd | | /workspace default | Reset to the default workspace (global cwd, no persona) |

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

Workspaces vs. lanes (v5.66.0): /workspace <name> is a global context switch — it always applies to the main conversation and, if you issue it inside a named lane, returns you to main without touching that lane's binding. A lane's workspace only ever changes through the explicit /lane <name> in <workspace>.

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 (500+ models, see below)

# 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

🔀 OpenRouter (bring your own key)

Alvin talks to OpenRouter through its OpenAI-compatible API, so a single key gives the bot access to 500+ models from Anthropic, OpenAI, Google, DeepSeek, Qwen and others — including a rotating set of free endpoints.

1. Create a key at https://openrouter.ai/settings/keys (your own — Alvin ships with none and never phones home with someone else's).
2. Put it in ~/.alvin-bot/.env:

   OPENROUTER_API_KEY=sk-or-v1-...

3. Wire models into the failover chain from any surface — Telegram, the terminal TUI or the web dashboard:

| Command | What it does | |---|---| | /openrouter | Overview: which OpenRouter models are in your chain, and your credit balance | | /openrouter free | Probe the currently free models and show which ones actually answer | | /openrouter search <text> | Search the full catalogue by name, e.g. /openrouter search qwen | | /openrouter add <model-id> | Add a model to the fallback chain, e.g. /openrouter add z-ai/glm-5.3 | | /openrouter rm <model-id> | Remove it again |

Models without native function calling still get tools: Alvin falls back to a text protocol in the system prompt and executes what the model emits, through the same allowlisted executor as native tool calls.

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 Baileys, a pure WebSocket client — the bot runs as your own WhatsApp account (not a separate business account). No Chrome or Puppeteer 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

| Mode | Env Variable | Description | |------|-------------|-------------| | Self-Chat | (always on) | Send yourself messages → bot responds. Your AI notepad. | | Groups | WHATSAPP_ALLOW_GROUPS=true | Bot responds in whitelisted groups. | | DMs | WHATSAPP_ALLOW_DMS=true | Bot responds to private messages from others. | | Self-Chat Only | WHATSAPP_SELF_CHAT_ONLY=true | Disables groups and DMs — only self-chat works. |

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/:

| Plugin | Description | |--------|-------------| | weather | Current weather & forecasts | | finance | Stock prices & crypto | | notes | Personal note-taking | | calendar | Calendar integration | | email | Email management | | smarthome | Smart home control |

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:

| Skill | Description | |---|---| | agent-browser | Token-efficient web automation via the agent-browser CLI (accessibility-tree snapshots) — Tier 1.5 of the browser stack | | apple-notes | Read, create, search Apple Notes via AppleScript (macOS) | | browse | 3-tier browser control: WebFetch · stealth Playwright · CDP with persistent profile | | code-project | Software development workflows: build, debug, refactor, architecture patterns | | data-analysis | CSV / JSON / Excel processing, charts, statistics via Python | | document-creation | PDFs, plus editable .pptx decks, .xlsx workbooks and .docx files | | email-summary | Inbox triage, newsletter digests, priority sorting | | github | Issues, PRs, releases, workflows via the gh CLI | | social-fetch | Analyse Instagram / TikTok / YouTube / X URLs the user shares | | summarize | Condense URLs, PDFs, long documents | | system-admin | Server management, deploys, Docker, nginx, SSL | | weather | Forecasts and conditions | | web-research | Deep multi-source research with citation aggregation | | webcheck | Security / SEO audit of a website |

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

GUI automation — omniclick (optional, macOS only, opt-in)

Clicks macOS interface elements by name. It takes a screenshot, runs OmniParser v2 over it to find labelled UI elements, and clicks the one you asked for via cliclick. Useful for the things a browser cannot reach: native apps, system dialogs, Electron windows with no usable DOM.

It is not installed by alvin-bot setup and it is not part of alvin-bot tools. You have to ask for it by name:

alvin-bot omniclick status             # Is it installed and ready?
alvin-bot omniclick install            # Guided install (asks before downloading)
alvin-bot omniclick doctor             # Full readiness check
alvin-bot omniclick uninstall          # Remove the checkout, weights and script

Once installed, the script it manages is driven directly:

~/.alvin-bot/scripts/omniclick.py snapshot                 # JSON of every detected element
~/.alvin-bot/scripts/omniclick.py click "Login"            # Find the best match and click it
~/.alvin-bot/scripts/omniclick.py click "Login" --dry-run  # Resolve only, never click

Read this before installing.

• macOS only. It needs screencapture and cliclick. On Linux and Windows every subcommand says so and exits without downloading anything.
• ~1.4 GB of model weights, plus a Python virtualenv that is roughly another 2 GB once torch is in it. install shows the numbers and your free space and waits for a yes.
• It controls your computer. It clicks in whatever application is in front. Treat it like any other tool with input access, and keep it away from untrusted instructions.
• macOS will ask for Screen Recording and Accessibility permission on first use. Without them the screenshot comes back blank — and the tool then refuses to click rather than clicking blind.
• It cannot unlock a locked screen. Synthetic events are echoed by the login window but never authenticated, and screen content is withheld while locked. Unlock via Screen Sharing/VNC first.
• The install is deliberately not a plain pip install -r requirements.txt: upstream's requirements include a Windows-only package, and two source-level fixes are needed before OmniParser imports at all on Apple Silicon. install applies them, then verifies the import actually succeeds.

Set OMNIPARSER_HOME to reuse an OmniParser checkout you already have, and OMNICLICK_DEVICE (mps / cpu / cuda) to choose the torch backend.

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

| Version | Theme | Highlights | |---|---|---| | v5.118.0 (September 2026) | Every provider answer says which level it means | /provider and /model name the scope they act on and, inside a lane, what that lane runs on — including when a chain fallback served the last turn. Slash-command suggestions recover from a failed fetch and respect Retry-After instead of falling silent for the life of the page. A first page load fetches only what it shows. Reads from the same machine get their own rate-limit budget; writes, login and every remote address stay exactly as strict. No capability removed. | | v5.117.0 (September 2026) | A subscription can be brought to setup, and being signed in now ends | Setup offers Codex CLI (ChatGPT plan) and a paid ollama.com account, each without an API key; the cloud card signs in from the browser and keeps the connect link across a redraw. Web sessions expire server-side, can be ended from the interface, and ending one takes the open socket, the stored history and the terminal with it. Every response carries nosniff, a referrer policy and a content policy narrowed to one named foreign file. The dashboard's three periodic queries rest while the page is hidden and catch up on return. Project repositories under the data directory stay writable. No capability removed. | | v5.97.0 (August 2026) | Each lane runs on the model you choose, and shows which one actually answered | Per-lane model pin (web UI + /lane model), origin shown on the column, the model that actually served the last turn named beside it, scheduled jobs honour their configured model | | v5.96.0 (August 2026) | A small local model can be given a context it can actually hold | A local model with a modest window was of little use as a fallback: anything longer was quietly truncated, so it never saw the question, called no tool, and the chain moved on with nothing logged. Lean context — switched on per model, offered only where it changes anything — trims a turn to what the model actually accepts. The window is measured rather than asked for, the conversation is shortened newest-first, the system prompt is built shorter rather than cut, tools are kept and counted against the budget, and the question itself is never shortened. Switchable from the web panel, a chat command and the terminal through one decision. Also: a custom provider's tool support is read from its own suitability verdict instead of guessed from a domain list, and the suitability run can now reach endpoints behind a key. No capability removed. | | v5.95.0 (August 2026) | A workspace can be given its own model, from the web UI | The field existed and worked, but nothing could write it, so the lane view's model column was blank everywhere. Each workspace row now has a dropdown and every lane bound to it follows. Photographs, voice, documents and video ignored that choice and answered on the global model while text in the same lane used the chosen one — all four now match. Model tiers moved from the provider switch to the model picker while staying selectable for workspaces and scheduled jobs, scheduled jobs stopped offering settings their type cannot use, and removing a model no longer leaves it on offer with nothing behind it. No capability removed. | | v5.94.0 (August 2026) | Every lane can run on its own model | A workspace names the model it works on and every lane bound to it uses it; the lane list shows which model runs where. Scheduled jobs deliver into the main conversation and can name their own lane and model, editable in place rather than by deleting and rebuilding the job. Several lanes on the same local model cost nothing extra — one loaded instance serves them all; several different ones get a note about the slowdown, never a refusal, since the combination works. The main conversation clears itself at local midnight, deferring while a lane is answering, and DAILY_LANE_RESET=off disables it. No capability removed. | | v5.93.1 (August 2026) | A failed download says so, and removing a model updates the fallback chain | The guard around the data directory now judges by destination rather than syntax. A pull that ended in an error was announced as finished; the pruned fallback chain was calculated and never written, leaving a removed model in the provider order. Both fixed, and a way of working figured out once can be recorded as a skill that loads only when a message matches it. No capability removed. | | v5.93.0 (August 2026) | Any Ollama model, tested before it is trusted | Models can be installed, registered and removed from the terminal, the web UI and chat, with a suitability check that exercises tool calling, sub-agents and browser use against the machine's actual memory and disk. Cloud models skip the hardware gate — they do not run here. Downloads survive a restart. No capability removed. | | v5.92.0 (August 2026) | Short answers are short in the way you meant | Verbosity settings now reach the model itself where the provider supports it, instead of only trimming afterwards. No capability removed. | | v5.91.1 (August 2026) | An Ollama daemon on a remote host, in Docker, or on Windows is now detected automatically | Three places assumed localhost:11434, a POSIX binary path, and a local daemon to test against — each a real setup (remote GPU box, Docker container, Windows laptop) that broke silently. OLLAMA_HOST/OLLAMA_BASE_URL now drive the model catalogue and the embeddings endpoint through one shared resolver, the PATH scan honours the Windows ; separator and ollama.exe install path, and the daemon smoke test skips cleanly when no daemon is running and runs as a real gate when one is. No capability removed. | | v5.91.0 (August 2026) | A workspace file that grows without bound no longer taxes every message | Notes kept in a workspace CLAUDE.md are read into every turn; a file grown past 400 KB was measured at roughly 280.000 tokens for a one-word answer. Dated records are now moved to sibling files on demand, rules stay resident, and nothing is ever lost — the rewrite is checked line by line and abandoned if even one line would go missing. No capability removed. | | v5.90 (August 2026) | Ollama's cloud models now work as a provider | Ollama Pro serves frontier models through the same local port as your downloaded ones; the bot used to declare them missing (they never appear in the local catalogue) and route them through the scaffold built for small local models, which returned an empty answer. Both are fixed, local models keep their behaviour unchanged. Also: the test suite no longer depends on whether an Ollama daemon happens to be running on the machine. No capability removed. | | v5.89.0 (August 2026) | The container setup works | Built from the npm package instead of a repo checkout, so there is nothing to clone and no COPY list to drift. alvin-bot docker init writes the templates where you want them. Chromium included; data in a named volume that survives --force-recreate; Web UI on loopback by default; log rotation and TZ set. Three plugins stopped storing user data inside the installed package. | | v5.88.0 (August 2026) | Lanes are created and bound to a workspace from the browser | The Lanes view creates its own lanes, assigns a workspace per column and can add a workspace without a text editor. Rebinding an existing lane is allowed and states its cost first — the column keeps its messages, the model loses the thread, and for a workspace that shares lane memory, that this lane's daily logs become readable by its siblings there, past days included. A working directory is stored verbatim or refused rather than normalised like prose, which could bind a workspace to a different directory that happened to exist. The workspace overview escapes what a workspace supplies. | | v5.87.0 (August 2026) | An adversarial build loop, in the background | /gauntlet [light\|medium\|heavy] <instruction> hands a task to a detached worker that implements it test-first, then sets independent critics on the result — each running the tests itself instead of trusting the worker's report. Only blockers (and majors from medium up) trigger another round. The chat stays free; /subagents cancel stops it. | | v5.86.0 (August 2026) | Lane columns became manageable from the browser | Per-lane reset, rename and delete; ordering by last activity so a finished lane stays where you were looking; tokens instead of dollars in the header; dates on every message; a count of running sub-agents; drag-and-drop upload streamed to disk under a size cap. Plus three fixes: answers vanishing from a column, a view left stale after a dropped connection, and a sub-agent's result painted as if the user had typed it. | | v5.85.0 (August 2026) | In-process poll recovery now actually recovers | The bot's in-process repair for stuck Telegram polling — restart the polling loop, not the whole process — used to be cut off a fraction of a second before it would have finished: the health check judged a freshly restarted loop by its predecessor's last success, with a grace period exactly as long as one poll request. Polling health is now judged against each loop's own start time, and the grace period is derived from the real poll timeout instead of coincidentally matching it. A genuinely stuck connection still escalates to a full restart, unchanged and covered by tests. No capability removed. | | v5.84.0 (August 2026) | A self-restart now makes sure it comes back | The bot's last-resort self-repair — restart itself when Telegram stops delivering but the connection is provably fine — used to be a plain exit trusting the operating system to notice. On macOS it now hands off to a small detached helper that waits for the old process to disappear and explicitly tells the service manager to start it again, backing off the moment a healthy replacement already exists; other platforms keep the previous behaviour. The owner message says which route was actually taken. Also: the bot now checks that its own outside safety-net watcher is still ticking and says so once if it has gone quiet. No capability removed. | | v5.83.0 (August 2026) | Background agents work from every message type | Voice, photo, document and video messages — and the web chat — now dispatch a real detached background agent instead of quietly falling back to an in-session helper that dies with the turn. Also: the automatic retry for a rare empty-answer turn no longer gets stuck for up to ten minutes; it starts with a clean channel and its own short deadline (60 s streaming / 300 s not, overridable), and reports a clear failure in seconds instead of silence. No capability removed. | | v5.82.0 (August 2026) | Every lane now works in its own live column in the browser | The web UI gained a Lanes view: one column per lane side by side, horizontally scrollable, working lanes sorted to the front, each with a status lamp, its workspace identity, today's cost and its own input box. A message written into a lane column runs through the full pipeline — same memory, same tools, same background agents — and the reply appears both in the chat and in the column. Plus a design refresh (new colour and spacing scale, collapsible nav sections, a command palette generated from the navigation instead of maintained by hand) that every page inherits, and first-class mobile with one column per screen and swipe paging. No capability removed. | | v5.81 (August 2026) | Answers appear as they are written | Replies now stream in word by word instead of arriving as one block at the end — in Telegram, the web UI, the terminal client and the OpenAI-compatible API alike. A shared turn registry with replay lets a client that reconnects mid-answer pick up exactly where it left off without losing or repeating text, and a per-chat edit budget keeps long answers from hitting platform rate limits. 5.81.1 then made the wait itself visible: the thinking phase before the first word now shows as a status instead of silence, and the update threshold was matched to the real packet size, so short answers stream too. Set TOKEN_STREAMING=0 to turn it all off. No capability removed. | | v5.80 (August 2026) | A background task writing its final report is no longer mistaken for a dead one | Long background agents were being declared crashed exactly at the finish line: writing a large final report produces no output for minutes, and that silence was read as death — the finished result was then thrown away. Silence alone no longer ends anything; a task is only declared failed on real evidence, a failure report now carries whatever partial output and token count exist instead of "(empty output)", and a result that lands after a wrong verdict is delivered as a correction, exactly once, even across a restart. 5.80.1 extended this to a stale process id: a transcript that is still growing outranks a process id that says otherwise. No capability removed. | | v5.79.0 (August 2026) | The bot repeats a failed request itself instead of asking you to | When a turn came back empty, the bot now retries it once on its own rather than handing you an empty reply to resend by hand. | | v5.77.0 (August 2026) | /verbosity now actually shortens answers | The verbosity setting was advertised but barely reached the model; short now means short. 5.77.1 and 5.78 were packaging housekeeping — the package ships an explicit file list. | | v5.76.0 (August 2026) | Background tasks are no longer reported as failed while they are still working | A first pass at the finish-line problem above: a running process is no longer declared stalled purely because it has been quiet. | | v5.73–v5.75 (August 2026) | Offline models became genuinely usable | Local models now pick tools as reliably as they answer questions, work through a multi-step task instead of answering a single question, and being offline delays a task rather than losing it. Model recommendations are measured across every tier instead of guessed. No capability removed. | | v5.72.2 (July 2026) | Reliable dates — no more guessed weekdays | The model has no clock, and several paths handed it a bare calendar date with no weekday, so any weekday it stated was a guess — occasionally off by one. Now an authoritative date/weekday/time/timezone block goes into every request, including background sub-agents and scheduled jobs (which previously received no date at all). For any other date the bot verifies the weekday against the system clock rather than deriving it, a fresh value explicitly overrides stale "today is …" lines further up a long conversation, and the timezone it prints is the one it actually used — with an optional BOT_TIMEZONE for servers and containers. No capability removed. | | v5.72 (July 2026) | Fable 5 + a deeper reasoning tier | Anthropic's newest flagship, Fable 5, and the deeper-than-high thinking tier it introduced were already supported by the model runtime but missing from the pickers. Fable now appears in /model alongside Opus/Sonnet/Haiku (Agent SDK and Claude Code bridge), and a new xhigh effort level sits between high and max in /effort — available in the Telegram command, the web dashboard, and per-workspace frontmatter, honoured by Fable 5 and the latest Opus. Providers that don't recognise the deeper tiers clamp xhigh/max down to high, so selecting it never breaks a request. 5.72.1 then cleared the stale Opus version pins that the Opus 5 release exposed: the setup wizard and API-key presets offer Opus 5 (id verified against the live API), the recommendation list prefers it with a graceful fallback, and the setup check reports the model the CLI actually chooses instead of a pinned guess. No capability removed. | | v5.68 (July 2026) | Context guard fixed — transcript-size metric | v5.67's guard misfired: it watched cumulative billing input-tokens (cache reads count per internal tool step), so heavy tool turns looked like "millions of tokens" and opt-in auto-refresh could restart a healthy session every couple of messages. Both guards now measure the real disease — the session transcript file size: warn at CONTEXT_WARN_MB (default 4 MB, re-warn after doubling), opt-in refresh at CONTEXT_AUTO_ROTATE_MB (fresh session starts small → natural hysteresis, cannot loop). Refresh suppresses the same-turn warning. Token vars deprecated + ignored with a log hint. No capability rem