# 🤖 Alvin Bot — Autonomous AI Agent

> **v1.5.165.0:** Alvin Live: talk to the whole agent, not just a voice model — and mute your microphone mid-call without hanging up. Real-time voice in the web interface, with every request handled by Alvin's lanes, tools, memory and sub-agents while you keep talking.

> 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 pairs a full agent SDK runtime with 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 installs a small multilingual search model that runs inside the bot (no Ollama, no key) and uses a built-in SQLite FTS5 keyword index until then, so recall works out of the box. It dispatches detached sub-agents as independent CLI 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 — v1.5.165.0 (October 2026):** **The one-line installer works on the first try** — after `curl … | bash` the installer asks whether to set up right away and starts the wizard; its `alvin-bot` launcher starts the bundled Node directly, so the command works before the terminal reloads its PATH, under launchd and in cron. Quiet output in four steps, npm noise in a log, and running the installer again repairs an install.
>
> **v1.5.164.1** *(October 2026)*: **Scheduled jobs no longer start twice after a long one** — after a long scheduled job, the scheduler re-reads every further job and checks it against the current time.
>
> **v1.5.164.0** *(October 2026)*: **A chat outage no longer holds up your answers** — when a messenger is down or slow, the turn still finishes right away: the answer is in the history and the web interface, and the messenger gets it through a persistent outbox as soon as it is back (in order, with one "delivered late" header, failed after 24 h). Messages sent while the bot restarts are no longer dropped.
>
> **v1.5.163.0** *(October 2026)*: **A clear message when the agent cannot start, and a watch for runaway processes** — if the agent CLI shows no sign of life within 90 seconds (usually a macOS permission prompt waiting on the Mac), the turn stops with a clear notice instead of a ten-minute wait. A new process watch reports orphaned processes that keep a CPU core busy for about an hour; stopping accidental leftovers of agent shells is opt-in (`ALVIN_PROZESS_WAECHTER=an`).
>
> **v1.5.162.3** *(October 2026)*: **Background agents keep their own helpers** — helpers a background agent starts get up to four hours to finish instead of ten minutes, and the agent waits for them instead of going to sleep. Command suggestions for `/restart` and `/update` are English.
>
> **v1.5.162.2** *(October 2026)*: **`/permissions` requests every macOS permission at once** — all protected folders, mounted drives, the folders your jobs use and System Events in one go, with a report (now including Accessibility) and direct links to the remaining settings pages. The model menu now marks entries that follow your default model.
>
> **v1.5.162.0** *(October 2026)*: **Keep working on your API key when the subscription runs low.** Choose per lane whether the full agent bills your subscription or your pay-per-use API key (default or one of three model tiers), with the API lane first in the fallback chain once a key is set; the key no longer reaches anything that should bill the subscription. Plus: scheduled jobs can start background agents, and the lane model menu is readable on the phone.
>
> **v1.5.161.2** *(October 2026)*: **Scheduled jobs are safe from a briefly unreadable job file.** If the job file is caught mid-rewrite, the bot no longer saves an empty list over your jobs, job results no longer cut emojis in half, and you get a notification when macOS blocks a folder your jobs use until a permission dialog is confirmed.
>
> **v1.5.161.0** *(October 2026)*: **Mute in Alvin Live.** While a call runs, the Mute button next to it (or the M key) turns your microphone off without hanging up: side conversations stay out of the call and are never taken as instructions, while Alvin keeps working and still tells you when results are ready. The server enforces the mute too, and the transcript notes it.
>
> **v1.5.160.2** *(October 2026)*: **Documentation in clearer, vendor-neutral words.** The README, handbook, Docker and security guides, the configuration templates and the package description describe the agent runtime in neutral terms. Provider ids, environment variables and commands stay exactly as they were, so installing and configuring the bot is unchanged; third-party components and their terms remain listed in full in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md). **One contact address:** questions, bug reports and security reports go to alvbln7@gmail.com.
>
> **v1.5.160.1** *(October 2026)*: **Messages during a reply are handled, not cut off.** If a background agent was running and you wrote while Alvin answered, the bot aborted the answer and showed "I got tangled"; a reply that is not waiting for the agent now keeps running and takes your message along. Agent results on Agent SDK lanes no longer start with a false "summary unavailable" note.
>
> **v1.5.160.0** *(October 2026)*: **Alvin Live, now with your choice of the working model.** Alvin Live connects real-time voice to the complete agent harness: Gemini Live listens and speaks, and everything that needs your data or an action runs in Alvin's lanes with their tools, memory, sub-agents and failover, several tasks in parallel while the conversation goes on. New in this release: the Live settings choose which model handles the tasks of a call (your fallback order still applies), task cards show the real state after you hang up, and "New session" starts without leftover results. Built into the web interface: a browser on your laptop or phone is enough.
>
> **v1.5.159.0** *(October 2026)*: **Alvin Live.** A new Live page in the web interface turns Alvin into a phone call: Gemini Live is the voice, and everything that needs your data, research or an action goes to Alvin in a lane with your model, tools and background agents. Interrupt at any time, speak any language, ask "how far is it?" or "stop that" and get the real state. Setup checks a pasted Gemini key with a real live connection (free tier available); the newest live model is used automatically, 30 voices with preview (default Leda), emotion and temperament on by default. Tasks run in the reserved `live` lane or a `live-<workspace>` lane and are not posted to Telegram. The page shows the transcript and the exact cost of each live session, priced from Google's price list.
>
> **v1.5.158.0** *(October 2026)*: **Memory search without Ollama.** `EMBEDDINGS_PROVIDER=lokal` runs multilingual-e5-small inside the bot, in its own process that ends after 15 idle minutes; on a real 20,349-section index it put the right source first for 19 of 28 questions, against 11 for nomic-embed-text. Installed with `alvin-bot embeddings lokal` (~230 MB), or by itself when no vector provider is set. **Ollama only while it is used.** With `OLLAMA_ON_DEMAND=true` the bot holds Ollama's port, starts Ollama on the first real request and stops it after `OLLAMA_IDLE_STOP_HOURS` (4) without use — for every caller, including the `ollama` CLI. **Running on a server:** `alvin-bot doctor` reads configuration from the environment, the pre-flight checks the data folder, a Web-UI-only instance no longer logs "degraded" every 30 seconds, and the Docker guide explains how the Agent SDK provider signs in inside a container.
>
> **v1.5.157.1** *(October 2026)*: **The Maintenance page loads again.** One failing request, such as a backup folder holding a symlink whose target is gone, no longer keeps the page on "Loading…": the backup list skips what it cannot read, the server answers a failing API route with a 500, and the page shows each failed part as a finding or a note while the rest stays usable. **Tool calls written as `<invoke>` text run.** A model that answers with `<invoke name="…"><parameter name="…">…</parameter></invoke>` instead of a structured call has it executed through the same command guard, as long as the message is exactly that one call to a tool offered in the turn.
>
> **v1.5.157.0** *(October 2026)*: **Private memory is private by default.** `memory/privat/` and dated topic notes are private without any setting, and a workspace grant opens only what is at least as specific as the private prefix (`privateQuellen: *` opens everything). Facts from compaction stay out of the shared `MEMORY.md`: main writes to `memory/privat/`, a workspace lane to `memory/ws-<workspace>/`, any other lane to its own folder. The index covers `projects/`, `research/`, `privat/`, workspace folders and lane subfolders, removes deleted files and searches vectors held in memory (scan 43 → 11 ms median). Removing a lane in Telegram or the web UI offers Archive (preselected) or Delete for good; deleting a user deletes that user's lanes and lane archives for good. The web UI's memory page shows every notes folder, the lane archive and workspace grants, and saving there works again; every prompt names its memory folder.
>
> **v1.5.156.2** *(October 2026)*: **Private memory stays where it belongs.** `PRIVATE_QUELLEN` in `.env` marks memory sources as private; they reach only the main lane and lanes whose workspace lists them under `privateQuellen:`, never other lanes, the messenger path or background callers. Project notes, semantic recall, `/recall`, the asset overview and `alvin-bot search` follow the same rule, and project notes now load only when a message names them instead of on any word like "2026". Without `PRIVATE_QUELLEN` nothing changes.
>
> **v1.5.156.1** *(October 2026)*: **The memory index catches up again with Ollama.** A short hiccup between Ollama and its model runner (`400 … /tokenize … connection reset by peer`) used to end the whole reindex, because a run stores its vectors only at the end and the Ollama path did not retry. Index building now retries such hiccups, server errors and dropped connections up to four times; a real error such as a missing model still fails at once. The search inside every turn keeps a single attempt, so no reply waits for a retry.
>
> **v1.5.156.0** *(September 2026)*: **Files the bot sends show up in the Web UI.** Images, PDFs and any other file the bot sends you on Telegram also appear in the lane column of the turn that produced them and, for your own web-chat turns, in the chat — images inline at their final size, everything else as a card with name, type, size and a download link. Agents and scheduled jobs send through the running bot with `curl -K "$ALVIN_MEDIEN_CURLRC"`; copies are kept for 30 days or up to 1 GB, and `MEDIEN_AKTIV=false` switches them off without touching delivery.
>
> **v1.5.155.0** *(September 2026)*: **Restarts no longer interrupt work by surprise.** A pill in the top bar shows running jobs, replies and agents, and every restart path offers to wait until they are done (at most `RESTART_WHEN_IDLE_MAX_MIN` minutes). The chat header gets a new-session button that works like `/new`, the desktop sidebar folds into an icon rail, lanes can be shown as a list, and the web files ship without source comments.
>
> **v1.5.154.0** *(September 2026)*: **The Web UI shows formatted replies properly.** Replies in the lanes and on the chat page render tables, headings, block quotes, horizontal lines, lists and links as such instead of raw symbols; code stays exactly as written, and emphasis applies only where it was meant — a calculation like `3 * 4 * 5` stays a calculation. Answers to commands such as `/status`, `/help` or `/lane` read as plain text with their line breaks. A lane with agents working in the background says so in words and learns at once when an agent starts or finishes; hovering shows what each one is doing. If you stop a reply halfway, the part you saw stays in the history and your next messages appear below it; a message sent while a reply is running is kept as well, and the lane refreshes right after compaction. Photo, document, voice and video turns now appear in the lane history on every provider, and the lane badge names the provider and model that answered. Link previews of pages not encoded in UTF-8 show the correct characters, long responses keep accents and emoji intact, finished background agents deliver their full result right away, the settings pages handle unusual names more strictly, and editing the fallback order always keeps your primary provider.
>
> **v1.5.153.0** *(September 2026)*: **Earlier messages carry the time they were sent.** A model behind an OpenAI-compatible endpoint used to receive the conversation history as bare text — no hint whether a message was nine minutes or a day old — and a smaller model guessed the distance badly. Each history message now starts with a bracketed timestamp in the bot's timezone, in the same form as `now` in the date anchor, and the system prompt explains once where it comes from and that the model must never write one itself. The current message is not stamped, older entries without a timestamp go unchanged, a history without stamps sends exactly the prompt it did before, and the Agent SDK path is untouched. Compaction names the window it summarised and shows the summariser each message's time. Daily memory logs and the "Today's Log" / "Yesterday's Log" sections now use the local date of the bot's timezone rather than the UTC date, so a note written at 00:21 no longer lands in yesterday's file.
>
> **v1.5.152.0** *(September 2026)*: **A message can ask for a briefing before it runs.** `/pp <request>` makes the bot write a short briefing for itself — the goal, the context it already knows, the constraints you wrote quoted verbatim, the output format and what "done" means — and append it beneath your unchanged text; the reply opens with one line saying what was added. Constraints are checked in code: anything not a word-aligned quote of your message is dropped, a lost "not" is dropped, a stray line break rejects the whole briefing, and role-play, step-by-step scaffolds, shouting and numeric length caps are refused. If the small model that writes the briefing is slow, fails or returns something invalid, your message runs exactly as typed — the six-second limit is enforced by the bot, not trusted to the provider. `/pro_prompting auto on` does the same for every task-shaped message; it is off by default, stays off until you switch it on, and never touches confirmations, replies to the bot's questions, steering notes, forwarded or quoted third-party text, cron jobs, autopilot turns or continuations. The briefing is written by a second model, by default from a different vendor than the one answering you — `/pro_prompting status` names it, `PRO_PROMPTING_MODEL` changes it; that model sees the message text and nothing else. Two operator switches stop it for everyone: `ALVIN_PRO_PROMPTING=off` at start, or the file `~/.alvin-bot/pro-prompting/AUS` at any time. Also repaired on the way: thinking models used on the bot's short-call path (lane titles, summaries, memory extraction) now get a reasoning level and stop returning empty output, and the Groq preset no longer points at a retired model. With the prefix absent and the automatic mode off, the prompt handed to your model is byte-identical to the previous release.
>
> **v1.5.151.0** *(September 2026)*: **A command aimed at a neighbouring service no longer restarts the bot.** The `launchctl` and `pkill` rules matched on the prefix of the job label and on the process name anywhere in a path, so a neighbouring service was never reached and the bot restarted instead. The full label counts now, a `pkill -f` pattern is measured against this process's real command line read from the process table, and every `pkill`/`killall` of a line is examined, not only the first. A foreign pattern is never compiled — its literal pieces are matched in order — so it cannot stall the synchronous tool path. The destructive-command guard reads the target of the `rm` that runs instead of the whole line: eight destructive spellings the line scan let through are covered, and a stray ` / ` elsewhere no longer refuses ordinary work.
>
> **v1.5.150.1** *(September 2026)*: **A cron retry after the round limit gets twice the budget on every provider.** When a scheduled AI job stopped at its 300 rounds, the retry was supposed to get 600 — but only the Agent SDK's wording ("max turns") was recognised, so jobs on GLM, Ollama and other OpenAI-compatible providers were retried against the same 300. Both wordings count now, and the delivery says "stopped at turn limit" instead of "error".
>
> **v1.5.150.0** *(September 2026)*: **A message sent mid-turn is no longer left behind.** Plain messages typed into a working lane were queued instead of steered whenever the lane ran on a different provider than the globally active one, and a queued message only moved when another one followed; `/btw` worked because it asked the open channel. Routing now asks the channel's actual reader, queued messages run as their own turn as soon as the running one ends (not after a stop), a steered message the turn never read is carried over instead of dropped, and the column badge reports what really happened. Every lane column has its own stop button — `/stopall` for that lane only, enabled only while something runs. Column headers are three fixed rows of one height in every column (measured in WebKit and Chromium, 360–1,400 px, with and without touch); the autopilot badge is never shortened, and reset no longer wears the refresh icon.
>
> **v1.5.149.1** *(September 2026)*: **The rest of the performance audit, finished.** The running version sits right-aligned next to "Connected", delivered over the WebSocket itself so the first page load stays at two requests. Lane columns rebuild once per turn instead of two to three times and keep the reader's position — at the rebuild, at the end of a turn and at an error line. The memory index replaces entries only after embedding, reuses unchanged vectors, caps sections at 2,000 characters, drops embedded base64 and cleans its legacy twin of `MEMORY.md` once. A single missed availability probe no longer escalates into a 25-second outage, video and setup checks leave the main thread, Inter is served locally, and the Ollama cloud context window was measured at 1,048,576 tokens with an explicit 400 beyond it.
>
> **v1.5.145.0** *(September 2026)*: **The service no longer runs throttled.** A ten-agent audit with three-sceptic verification found the bot pinned to the efficiency cores since its first release (`ProcessType=Background`): priority 4 instead of 20, CPU-bound work 3.1–5.6× slower, a speech synthesis 10.7–12.4 s instead of 2.3, inherited by every detached agent and shell tool. Fixed, along with the Supertonic readiness probe (five synchronous process starts, polled every 8 s = ~6 % of the time frozen), a status poll that kept running on a page you had left, and an audio context leaked once per chat turn.
>
> **v1.5.144.2** *(September 2026)*: **Read-aloud no longer pauses the bot.** Supertonic's readiness probe started three processes synchronously before every synthesis; under load it overran its 3-s limit, stalled the main thread and falsely fell back to Edge. It now runs only until the first successful synthesis (the boot pre-warm counts) and again after a failure.
>
> **v1.5.144.1** *(September 2026)*: **The startup database check no longer freezes the bot.** `PRAGMA quick_check` on the memory database ran synchronously on the main thread; under I/O pressure it took up to 78 s, during which every timer and answer waited and the web interface was unreachable. It now runs in a worker thread — same check, same verdict, main thread free; a late verdict is reported when it arrives. Failed stall captures are logged with their reason; the read-aloud cache is fully asynchronous.
>
> **v1.5.144.0** *(September 2026)*: **Hear the whole turn, and have a reply read aloud.** Two new cues — `Thinking` the moment the bot becomes active, `Writing` at the first streamed character — complete the arc with `Sent` and `Reply`, each with its own switch. And every reply carries a small play button: one tap speaks it in the bot's own voice (the same one voice replies use), a second tap stops it; generated only on tap, cached per text, capped at 60 MB.
>
> **v1.5.143.0** *(September 2026)*: **The login screen names its version, and versions now read as v1.** The web interface asked for a password without saying what was behind it; the login page now shows the running version, served by a small public `GET /api/version`. And what a person reads is now `v1.5.143.0` — the leading one marks the first mature generation, the three numbers behind it stay exactly what npm publishes. Everything that compares versions keeps using the package number; a test fails the build if the display string ever reaches a calculating path.
>
> **v5.142.3** *(September 2026)*: **A stall is caught in the act.** The loop watchdog had recorded three stalls of 57–78 s with no culprit named; now a second thread reads a heartbeat every second and, when it stops for three seconds, captures the main thread's native stack with `sample` while it is still stuck — the blocking call lands in `loop-stall.log`. Breadcrumbs mark startup phases, the start of a turn and plugin tools.
>
> **v5.142.2** *(September 2026)*: **The web interface no longer warms up your phone.** At idle, with no JavaScript running, the page used 26.6 % of a CPU core — the sidebar's green "connected" dot pulsed by animating its shadow, which the browser repainted on every frame, on every page, for the whole session. Animations now move only opacity and transform, the dot breathes three times after connecting and then rests, and idle usage is 0.5 %.
>
> **v5.142.1** *(September 2026)*: **Sound cues, now on iOS too — and switchable one by one.** On an iPhone only the on/off button's tone played: the cues suspended their audio context after six seconds of quiet, and iOS will not resume it outside a tap. The suspension is gone, the context is created on your first tap, and it is woken when the tab returns from the background. Every cue has its own switch under Settings, with a preview beside it.
>
> **v5.142.0** *(September 2026)*: **Sound cues.** The web interface plays short synthetic tones for what the bot is doing — a reply finished, an agent started or done, an autopilot switched on, each run (duller when it brought nothing new), switched off, an error, a provider switch. Eleven cues, none over 0.6 s, built on the spot from two or three oscillators: no audio files, nothing running while idle, and a cooldown so five runs in a second are one ping. On/off, volume and a preview per cue live under Settings, plus a Sound button in the sidebar.
>
> **v5.141.0** *(September 2026)*: **Web search fails honestly instead of on its own parser.** `web_search` on the generic lane crashed with "Unexpected end of JSON input" when DuckDuckGo throttled; its fallback used `grep -oP`, which macOS does not have, so it could never return anything there. Both are fixed, results are extracted in JavaScript, and a bot challenge (which both engines now serve to command-line requests) is reported as such — not as "no results". The system doctor's "Empty values found in .env" warning now names the keys and is informational: empty means off.
>
> **v5.140.0** *(September 2026)*: **Workspaces can be removed.** Creating one has always been possible from the web interface; removing one was not — the only way was to delete the `.md` by hand. Each card now has a Remove button, and Telegram gains `/workspace rm <name>`. Both name what is bound to it first: which lanes lose their binding, how many sessions fall back to the default directory, how many users have it active. All three are released when it goes, so no lane keeps running in the wrong directory unannounced. `default` stays, and so do the working directory, every message and the lanes themselves.
>
> **v5.139.0** *(September 2026)*: **Nothing blocks, nothing freezes, nothing stops at a limit.** A conversation's system prompt is recorded once by the agent CLI and reused verbatim — so everything that changes now travels with the message instead, and a session that runs for days no longer answers with the time it started. Hitting a quota locks that account until its stated reset and the answer comes from the next link of your chain, with one line saying so. Shell and Python may take ten minutes instead of thirty seconds. Reading a file no longer halts the whole bot, and if the loop stalls anyway, a watchdog writes down how long and at what. Background agents get the same permissions as the chat, the fencing of external content works again after two months of being silently rejected, `ALVIN_FREIE_HAND=1` lifts every tool guard for owners who want that, and the web interface's Cron page gains filters and bulk actions.
>
> **v5.138.0** *(September 2026)*: **Autopilot off means off — including what it started.** Jobs and background agents an autopilot run starts now remember that run. `/autopilot off` lists whatever of it is still running, with buttons to pause the jobs, stop the agents, or keep them; the same list arrives when a run ends at one of your limits or its lane is removed. Nothing stops without a tap, jobs are paused rather than deleted, and jobs you asked for yourself never appear. A background agent that finishes after its run has ended hands over to a normal turn, and `/cron` and the web job card show where a job came from.
>
> **v5.137.1** *(September 2026)*: **Lane titles are back — light, stable and never in the way.** A lane you have not named gets a short title for what it is about right now, in the web board and in `/lanes` on Telegram. It stays while the topic stays and changes when the conversation moves on: a local check decides without any model call, and only a real topic change asks the lane's own model — once, over its lightest route, after the answer, cancelled the moment you write again. Returning to an earlier topic brings its title back for free, and a name you typed always wins. Since v5.137.1, clearing a lane's name titles it from its conversation right away, also directly after a restart.
>
> **v5.136.0** *(September 2026)*: **You decide which Agent SDK model runs, everywhere it runs.** Without a choice of your own, the Agent SDK provider now runs on its vendor's top tier — always the newest one. `/provider` sets the Agent SDK's model for everything that has no model of its own (conversations and lanes without a pin, background agents, scheduled jobs on the Agent SDK provider), and model choices — including the web chat's header — say what that entry runs today. `/model` only ever changes the lane you are in, and a provider that is a single model says so instead of offering a list that does not apply. Every scheduled AI job gets its own effort setting next to its model; jobs without one now run at medium like a conversation. Your `/effort` counts the same for text, photos, voice, video, documents, the other chat platforms and the web dashboard, and background agents follow the effort of the turn that started them.
>
> **v5.133.0** *(September 2026)*: **The bot measures its own hands, and gains eyes and a reader.** A local model is no longer routed by its address: it is measured once — native tool calls, the text protocol, a read-then-write chain — and afterwards takes the simplest path it actually passed, with the offline harness kept as the fallback for the models that need it. `/status` and `alvin-bot doctor` show a `🖐 Hands:` line, `/model test` measures again, `WERKZEUGWEG` forces a path. A model without vision now gets the bot's eyes: the macOS Vision framework first, a **local** vision model in Ollama second, delivered as a fenced description — with `read_image` taking a question and `look_again` asking about the last image. PDFs and Office files arrive as text on every lane outside the Agent SDK, on upload and through the new `read_document` tool, read on macOS with PDFKit before any command-line helper. And the harness is honest: a silent model yields an error instead of an echo of its own plan, facts travel between steps, and a task it cannot carry finishes in the plain tool loop of the same turn.
>
> **v5.132.1** *(September 2026)*: **Correction release.** A password or API key saved through the setup wizard, `/setup key`, the environment editor or `alvin-bot setup` is stored in the form the bot reads back on start — a `#`, a space or a quote in the value no longer changes it between "saved" and "running". Link previews classify destinations with the bot's shared network guard and connect to the exact address they checked. `read_image` asks the resizer for PNG explicitly. Autopilot `on` sees its own ending in `laut` mode, keeps watching after a failed run, keeps a replaced run's turn out of its successor, and `on budget 5` sets a budget. The heartbeat fails over along the chain in effect, a background result arrives as capped text when its upload does not, a file sends without a caption, and `$` survives Iterate.
>
> **v5.132.0** *(September 2026)*: **The web UI answers, iterates and previews.** Every message gains two buttons — Reply quotes what it sits on, Iterate sends the bot's own result back to it to assess what is weak and improve only where there is something substantial, ending with an honest verdict ("Improved: …" or "Nothing substantial to improve, because …"). Links in bot messages arrive as preview cards — title, domain, description, thumbnail — loaded lazily when the bubble scrolls into view, silent on failure. And autopilot gains an **"on" mode**: the lane derives its task from its own context, works until done, announces the hand-off, and then watches — a typed message in the lane prompts a rate-limited look-around, while its own turns never do; the status line shows `on · working/watching`.
>
> **v5.131.0** *(September 2026)*: **Images reach the model as images.** A new `read_image` tool hands local PNG, JPEG, WebP and GIF files to the model as a picture — the format read from the content, oversized images downscaled instead of rejected — and a tool result's image survives the redirect to GLM, OpenRouter or a local Ollama as its own message instead of arriving as a "not forwarded" note; MCP clients see real image content. Telegram replies that quote foreign text — a group title, a job name, a model tag with an underscore — used to die whole on one character; every such spot escapes the text now, and the ollama model-card buttons take the same routes as the typed commands. Promoting a fallback provider is one decision everywhere, a held chain holds for a pinned lane, and promised work arrives: no paid follow-up turn after an autopilot is switched off, no double delivery after a restart, and on Slack, Discord and WhatsApp a background agent's result reaches the session history too. Attachments count as delivered only when the upload actually went through.
>
> **v5.130.0** *(September 2026)*: **In an autopilot run, a finding is a task, not an offer.** Every autopilot run tells the model its situation — nobody is reading along, nobody will answer a question; fix, verify, report — and a run that still ends with a question gets one follow-up in the same run, and no more.
>
> **v5.129.0** *(September 2026)*: **A background agent's result now lands in the lane it was started from.** The web dashboard's lane column renders the lane's history, and on the default Telegram delivery path that history only ever received a truncated completion note — the summary itself went to Telegram alone. Both delivery paths now write the same three entries (status line, summary, attribution note), the completion note no longer claims a delivery it cannot see, and its excerpt ends at a sentence. Also: a lane whose workspace folder has disappeared no longer throws inside the bot when an agent is started — the agent answers with a clear message instead.
>
> **v5.128.0** *(September 2026)*: **Model names are looked up, not remembered.** Every list of Agent SDK and OpenAI models — `/model`, the dashboard, the setup wizard, `/status` — now comes from the live catalogues: your API key, your signed-in agent CLI (the same list its own `/model` shows, no key and no tokens needed), or OpenRouter's public catalogue, cached for six hours and refreshed in the background, without a cron. The tier aliases keep working and now say which model they resolve to today. A new `openai-latest` provider runs whatever GPT flagship exists on the day the bot starts, and with an OpenAI key the model list finally includes the current generation instead of stopping at GPT-4. Every list names its source and date; a short built-in list is the last resort only.
>
> **v5.127.0** *(September 2026)*: **Voice messages are transcribed on your own machine.** A local Whisper is used when one is installed — no key, no network, nothing leaving the box; on an Apple M4 a five-minute message takes about eleven seconds. Groq remains the fallback and the reason for every switch is logged. Errors from the speech API now say what happened instead of collapsing into "could not understand the voice message".
>
> **v5.91.0** *(August 2026)*: **A workspace file that grows without bound no longer taxes every message.** Notes kept in a workspace's project rules file 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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)
>
> **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 →](CHANGELOG.md)

---

## ✨ Features

### 🧠 Intelligence
- **Multi-model engine** — 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 · lokal (in-process, no Ollama/key) · 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** — Agent 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 ↓](#-multi-session-workspaces-v4120)
- **Detached sub-agents** — `alvin_dispatch_agent` MCP tool spawns independent CLI 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 ↓](#-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** — speech-to-text on your own machine via Whisper (no key, no network), Groq as the fallback; 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

### Files in the Web UI

Every file the bot sends you (images, PDFs, any file) also appears in the Web UI: in the lane
column of the turn that produced it and, for your own web-chat turns, in the chat. Agents and
cron jobs send files through the running bot:

    curl -K "$ALVIN_MEDIEN_CURLRC" --data-urlencode "pfad=/abs/report.pdf" --data-urlencode "caption=Weekly report"

This needs curl 8.3.0 or newer. For people at a terminal there is a convenience command, run
from the installation directory: `node <install dir>/bin/cli.js send-file <path> [--caption …]`.

---

## ⚖️ 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 | 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 CLI 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 desktop AI apps / 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 |
| Real-time voice | **Built into the web UI (laptop or phone browser, no telephony or plugin)**: Gemini Live is the voice, every request runs through the full harness in parallel lanes while you keep talking; exact cost per voice session | Built-in voice mode (CLI push-to-talk, Discord voice); continuous talk-while-it-works via community add-ons | Voice Call plugin with real-time Gemini Live / OpenAI over Twilio or Telnyx, consulting the main agent; voice activation in native apps |
| 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 has a full agent SDK runtime at its core — 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 desktop AI apps / 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.

---

## 🚀 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):

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

It reuses an existing Node 22 or newer (not 23) 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 asks whether to start the setup wizard right
away. Run it again any time to repair an install.

**Already have Node 22+?** The classic three commands work too (Node 18 and 20
also work, but only with a C++ compiler for the database module):

```bash
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](https://t.me/BotFather)) · your Telegram user ID ([@userinfobot](https://t.me/userinfobot)). Node.js 22+ ([nodejs.org](https://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).

### 🪟 Windows

Alvin runs on Windows inside WSL: open the WSL Linux shell and install it there with the commands above. For 24/7 operation, add a Task Scheduler entry that starts it at logon.

### 🔐 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 sign the Agent SDK provider in with a subscription, run the bot as a **LaunchAgent** — it inherits the GUI login session so the macOS Keychain stays unlocked and the CLI's OAuth token just works without any manual `security unlock-keychain` dance:

```bash
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 the Agent SDK provider, `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`](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 | The newest GPT, picked for you (`openai-latest`) |
| OpenRouter | Paid | 100+ models marketplace |
| Agent SDK (`claude-sdk`) | Paid* | Full agent with tool use |

\*The Agent SDK provider needs a subscription or API access with the SDK's vendor: a signed-in CLI (`claude login`) or `ANTHROPIC_API_KEY`. The setup wizard checks this automatically.

#### Model names stay current — no cron, no release

Model vendors ship new models faster than any bot can hard-code their
names. Alvin therefore looks them up instead of remembering them. Whenever a
list of models is shown — `/model`, the models page of the dashboard, the
setup wizard, `/status` — the bot asks, in this order:

| Family | Sources, first answer wins |
|--------|----------------------------|
| Agent SDK | your API key (above) → your signed-in **agent CLI** (no key, no tokens; the same list its own `/model` shows) → OpenRouter's public catalogue |
| OpenAI | your `OPENAI_API_KEY` → OpenRouter's public catalogue |

The answer is cached for six hours (memory and `~/.alvin-bot/model-directory.json`)
and refreshed in the background when it is older; nothing runs on a schedule,
and a network that does not answer never blocks a page. Every list says where
it came from and when. Only if every source fails does a short built-in list
apply, and it says so.

What this changes in practice:

- The tier aliases `opus`, `sonnet`, `haiku` and `fable` keep working exactly
  as before, and every place that shows them also shows which model they
  resolve to today.
- `openai-latest` follows the newest OpenAI model the way the Agent SDK's
  auto-latest preset does: it runs whatever GPT flagship exists on the day the bot starts. `OPENAI_MODEL` still
  pins a specific model.
- With an OpenAI key, `/model` lists every chat-capable model your key can
  reach, current generation included.

`MODEL_DIRECTORY=off` disables all lookups (air-gapped hosts); the built-in list
is then the only source.

### Alternative Installation

<details>
<summary>One-line install script (Linux/macOS) — mirror URL</summary>

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

```bash
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 offers to run the setup wizard right away.
</details>

<details>
<summary>Desktop App (macOS)</summary>

| 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.
</details>

<details>
<summary>Docker</summary>

```bash
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.

**The Agent SDK provider in a container** — run `claude setup-token` once on your own machine
and put the token in `.env` as `CLAUDE_CODE_OAUTH_TOKEN` (with
`PRIMARY_PROVIDER=claude-sdk`). Groq, Gemini, OpenAI or a local Ollama work too.

Full guide: [docs/install/docker.md](docs/install/docker.md)
</details>

<details>
<summary>Production (PM2)</summary>

```bash
npm install -g pm2
pm2 start ecosystem.config.cjs
pm2 save && pm2 startup
```
</details>

### Troubleshooting

```bash
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` | Choose the model of the lane you are in (inline keyboard) |
| `/effort <low\|medium\|high\|xhigh\|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 |
| `/kontingent` (alias `/quota`) | Show quota locks, release them (`frei`), or set a test lock (`test 2m`) — while an account is used up, the fallback chain answers |
| `/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) |
| `/workspace rm <name>` | Remove a workspace — names what is bound to it first, then `confirm` deletes it (v5.140.0). The working directory and every message stay |
| `/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) |
| `/finish` | Wrap up the current turn — the model finishes its thought and stops |
| `/pp <request>` | Refine this one message before it runs |
| `/pro_prompting` | Automatic refinement on/off, status, own entries |
| `/lane <name>` | Switch to (or create) a lane — a parallel workstream with its own context |
| `/focus <name>` | Alias of `/lane` |
| `/lanes` | Dashboard of all lanes |
| `/autopilot <task…>` | This lane keeps working on it alone until you stop it |
| `/provider` | Which provider serves this conversation; switch the global one and its Agent SDK sub-model |
| `/models` | Browse and pin models |
| `/ollama` | Manage local and cloud Ollama models |
| `/openrouter` | Manage OpenRouter models |
| `/memory` | Inspect what has been remembered |
| `/reindex` | Rebuild the memory index |
| `/note <text>` | File a note without starting a turn |
| `/tools` | Which tools the serving model actually has |
| `/sub_agents` | Background agents: what is running, what came back |
| `/browse <url>` | Fetch and read a page |
| `/webui` | Open the web interface |
| `/mcp` | Manage MCP servers |
| `/plugins` | Manage plugins |
| `/groups` | Group-chat settings |
| `/security` | Security posture and permissions |
| `/users` | Who may talk to this bot |
| `/lean` | Trim the context for small local models |
| `/autoupdate <on\|off>` | Automatic updates |
| `/version` | Which version is running |
| `/ping` | Is it alive |
| `/about` | What this does, whose terms apply, and that use is at your own risk |

---

## 🏗️ Architecture

```
  Telegram   Slack   WhatsApp   Discord   Signal   Web UI · TUI · CLI
      └─────────┴─────────┴────┬────┴─────────┴───────────┘
                               ▼
              Workspace Resolver  (per-channel cwd + persona)
                               ▼
                 Engine  (routing · fallback · heartbeat)
        ┌──────────────────────┼───────────────────────────┐
        ▼                      ▼                            ▼
   Agent 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 CLI processes, 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 |
|---|---|---|---|---|
| Agent SDK | ✅ native (Bash, Read, Write, Web, MCP) | ✅ | ✅ | CLI OAuth or API key |
| 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/               Agent 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
```

---

## 🛣️ Lanes — parallel workstreams

A lane is a separate line of work with its own conversation, its own context and
its own model. Switching lanes does not disturb the others; they can run at the
same time.

```
/lane research          # switch to it, or create it on first use
/lanes                  # dashboard: what each lane is doing, what it costs
/lane research in ops   # bind a lane to a workspace (persona, cwd, model)
/lane model research groq   # pin one model to one lane
/lane budget research 5     # per-day spend cap for that lane alone
/lane rm research           # remove it, with its conversation
```

You can also address a lane without leaving the one you are in:

```
@research: check whether the export finished
```

`main` is the ordinary conversation. It is a lane like the others in most
respects, but it follows `/provider` globally rather than a per-lane pin.

### Autopilot — a lane that keeps working on its own

Switch a lane to autopilot and it carries on without you typing. The task is
sent again on every run, unchanged.

```
/autopilot work through the migration checklist step by step
/autopilot status
/autopilot off
```

**It runs until you stop it.** There is no run limit and no spend limit unless
you set one — most people run on a subscription, where a run is not a billing
event. Limits are yours to choose:

```
/autopilot draft the release notes every 30m
/autopilot review the open tickets max 50
/autopilot summarise new mail budget 5
/autopilot watch the build every 15m max 100 budget 2.50 laut
```

| Switch | Effect |
|---|---|
| `every 30m` / `every 2h` | Your own interval (default 2h, from 1 minute to 7 days) |
| `max 50` | Stop after that many runs |
| `budget 5` | Stop at that spend, in USD, counted across the whole run |
| `laut` | Post every run in the chat (default: quiet) |

Switches are only read at the **end** of the line, so `check the filing every
45 min` stays a task rather than being cut in half.

By default a run is **quiet**: it appears in the lane column of the web
interface, while the chat gets the start, the end, and anything that goes
wrong. Twenty-four runs over two days would otherwise be two dozen messages,
half of them at night.

If the same answer comes back three times in a row you get **one** notice and
it keeps going — three times the same thing usually means stuck, but sometimes
it means legitimately waiting, and only you can tell those apart.

**A finding is a task, not an offer.** Every autopilot run tells the model
what situation it is in: nobody is reading along and nobody will answer a
question. Something it notices within the lane's assignment gets fixed,
verified and reported as done — not offered with "let me know if I should".
Only what is irreversible, outside the assignment, or spends money with a
third party stays undone, stated in one sentence, and the run carries on.
Open points from the previous run are the next run's first task, and
background agents started from an autopilot run work under the same rules.
Should a run still end with a question or an offer, the autopilot follows up
**once** in the same run ("nobody will answer — do it now") and then leaves it
at that; a second follow-up would be a loop. When you type into the lane
yourself, none of this applies — you are there to answer.

**Off means off — including what it started.** A run may schedule jobs and
start background agents; both remember the run that created them, also when a
tool writes a job straight into the job file while the run is the only one
working in that chat. `/autopilot
off` lists whatever of it is still running under its confirmation, with
buttons: pause the jobs, stop the agents, stop both, or keep them running.
Nothing stops without a tap, and jobs are paused, not deleted — `/cron`
resumes them. The same list arrives when a run ends at one of your limits and
when you remove the lane. Jobs you ask for yourself in the lane's conversation
never appear on it. A background agent that finishes after its run has ended
hands its result to a normal turn, not an unattended one.

Three things it will not do: no lane carries an autopilot of its own accord,
there is no global switch, and `main` cannot have one — `main` *is* the
conversation.

> **You are responsible for what it does.** It acts under your accounts and
> your credentials, unattended, for as long as you leave it running. See
> `/about`.

## 🎙️ Local speech-to-text

Voice messages are transcribed **on your own machine** when a local Whisper is
available. No key, no network, nothing leaving the box. Groq stays as the
fallback, so nothing breaks if you have neither.

Measured on an Apple M4, model `small`, German speech:

| Path | 22 s of speech | A 5-minute message |
|---|---|---|
| whisper.cpp (warm) | 1.1 s — 21× real time | ~11 s |
| whisper.cpp (first run after boot) | 14.3 s | model load + Metal shader compile, once |
| openai-whisper (Python) | 9.7 s — 2.3× real time | ~2 min |
| Groq API | network round trip | needs `GROQ_API_KEY` |

**Setup — whisper.cpp (recommended):**

```bash
brew install whisper-cpp        # the whisper.cpp project's own CLI
```

**That is the only step.** On the next start the bot notices the binary, fetches
the `small` model (466 MB) into `~/.alvin-bot/whisper-models` once, and
transcribes locally from then on. `ggml-medium.bin` and `ggml-large-v3-turbo.bin`
are more accurate and slower, and are preferred automatically if you put them
there yourself. The Python `openai-whisper` package works too and is used if it
is the only one installed — it manages its own models.

The model is fetched **only** when the binary is already present: without it the
file would be useless, and half a gigabyte on the off-chance is not something
software should help itself to. `WHISPER_AUTO_DOWNLOAD=off` prevents it
entirely. It lives in your bot state directory, not in the package, so an
update does not fetch it again.

**Why the binary is not in the package:** the npm packages that bundle
whisper.cpp compile it during installation. A compiler error on any machine
would then break `npm install` of the bot itself — too high a price for one
feature. It stays a `brew install` you run once.

The local path fails **softly**: no binary, missing model, timeout, nothing
recognised — Groq takes over and the reason is written to the log. If neither
is available you are told exactly that, rather than "could not understand".

**`GROQ_API_KEY` is no longer required for voice.** Until v5.126 the three
places that accept voice — Telegram, video audio, and the other platforms —
each checked for that key before transcribing, so a machine with a working
local Whisper and no Groq account refused every voice message. They now ask
whether *a* path exists.

| Variable | Default | What it does |
|---|---|---|
| `STT_LOCAL` | on | `off` disables the local path entirely |
| `STT_PREFER` | local | `groq` tries the network first, local as fallback |
| `WHISPER_MODEL_DIR` | `~/.alvin-bot/whisper-models` | where models are looked for |
| `WHISPER_MODEL_FILE` | — | one specific model file, overriding the search |
| `WHISPER_MODEL` | `small` | model name for the Python `openai-whisper` |
| `WHISPER_LANGUAGE` | `auto` | force a language instead of detecting it |
| `WHISPER_TIMEOUT_MS` | `300000` | give up after this long and fall back |
| `WHISPER_AUTO_DOWNLOAD` | on | `off` never fetches the model automatically |

## 🔀 The Agent SDK lane on any provider

The Agent SDK lane is the one with the full machinery: tools, sub-agents,
project rules, streaming. It speaks its vendor's own protocol, which used to
mean it needed an account with that vendor — or Ollama, which happens to serve
that protocol itself.

A local translator removes that constraint. It accepts `POST /v1/messages` and
forwards it as `POST /v1/chat/completions`, so the same machinery runs on
OpenRouter, a private endpoint, or anything else that speaks the OpenAI shape.

```bash
CLAUDE_SDK_DOLMETSCHER_URL=https://openrouter.ai/api
CLAUDE_SDK_DOLMETSCHER_MODEL=<provider/model>
CLAUDE_SDK_DOLMETSCHER_KEY=<your key>
CLAUDE_SDK_DOLMETSCHER_WINDOW=131072   # the target model's context window
CLAUDE_SDK_DOLMETSCHER_SCHEMA=lenient  # or "strict" for pickier endpoints
```

It binds to loopback only — it carries someone else's credentials — and it is
off unless configured. A failed start deliberately does **not** fall back to
the normal path: silently billing an account while the interface claims a local
endpoint is the most expensive failure available.

Set `…_WINDOW` if you know it. The client compacts its own history by asking how
large the input is and comparing that against its vendor's window; behind the
translator sits a model whose window may be a tenth of that. With the window
known, the count is converted into the scale the client thinks in, so compaction
happens at the right point instead of never.

## 🧭 Multi-Session Workspaces (v4.12.0)

**Run multiple parallel Alvin sessions on the same bot — one per project, context-isolated, memory shared.** 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, the model mixes one context into the other. Workspaces solve this: **Slack channel = session**, or on Telegram, **`/workspace my-project` = session**. Each one has its own Agent SDK `resume` token, history, and the current project's rules file 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`:

```markdown
---
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 the Agent 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](#lanes) 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.

**Private memory (v5.156.2, extended in v5.157.0):** `memory/privat/` and dated topic notes (`memory/YYYY-MM-DD-<topic>.md`) are always private. `PRIVATE_QUELLEN` in `.env` adds more source prefixes, for example `PRIVATE_QUELLEN=memory/projects/,assets/legal/`; it cannot remove the built-in ones. A private source reaches only the main lane and lanes whose workspace frontmatter lists it, e.g. `privateQuellen: memory/projects/, assets/legal/` (a folder prefix or a single file such as `memory/projects/side-job.md`). A grant counts only if it is at least as specific as the private prefix covering the source, so `privateQuellen: hub/` does not open a hub file that is listed as private on its own; `privateQuellen: *` opens every private source and `privateQuellen: datierte-notizen` the dated topic notes; archived lanes under `memory/archiv/` stay with the main lane only. Other lanes, the messenger path and background callers without a lane never see them — in project notes, recall, `/recall`, the asset overview or `alvin-bot search`. Changed in the web interface (Settings → Environment Variables), the list takes effect at once; the editor starts from the current list and asks before saving one that drops a prefix (v5.157.0). Facts that a workspace lane's conversation produces go to `memory/ws-<workspace>/auszug.md`, visible to the main lane and that workspace; a lane whose workspace sees `memory/privat/` writes to `memory/privat/auszug.md`, and a lane without a workspace to its own lane folder.

**Memory folder per lane (v5.157.0):** the system prompt names each lane's memory folder as an absolute path — `~/.alvin-bot/memory` for main, `~/.alvin-bot/memory/lane-<name>` for every other lane — so notes no longer land wherever the session's working directory happens to be. Only the main lane and lanes whose workspace `privateQuellen:` opens `memory/privat/` (for example `*`) are also told the private notes folder `~/.alvin-bot/memory/privat/`; no other lane gets a pointer to it. Background agents carry the same lines in their task and start in their session's working directory; sub-agents and cron runs use the main folder, and a cron job that delivers into a lane names the private notes folder only if that lane may see it; the checkpoint reminder of long sessions names the folder too. A workspace can point its lanes elsewhere with `gedaechtnis: ~/path/to/memory` in the frontmatter or on the memory page (not in `default.md` or a workspace file whose name breaks the naming rule of lowercase letters, digits and hyphens; absolute or starting with `~/`, without `..`; not `/`, your home folder or a folder that contains `~/.alvin-bot/memory`, nothing inside it except the workspace's own `memory/ws-<name>/`, and not `~/memory` or `memory/` in the install directory, the places the stray-folder check reports, symlinks included; anything else is ignored with a log line, and the memory page refuses it and points out a value in the file it ignores; saving only the grants leaves that line alone). Removing a lane archives `memory/lane-<name>/` to `memory/archiv/lane-<name>-<date>/` by default; deleting it for good takes a second confirmation. Deleting a user in the web interface deletes each of their lanes for good, folder and index entries included, without archiving, and the archived lanes they removed earlier as well; this cannot be undone. A folder set with `gedaechtnis:` is never deleted or moved by either. If a `memory/` folder shows up in the install directory or in your home folder, the startup log and the doctor report it as an error. The doctor also warns when a hub note has a copy of the same name in the memory root that reaches lanes the hub note does not (a dated copy opened by `datierte-notizen`, an undated one open to every lane); list the copy itself in `PRIVATE_QUELLEN` (`memory/<file>`) or move it to `memory/privat/`.

**File index in the system prompt (v5.121.0, on by default):** where the workspace text above names `.md` files that exist in its `cwd` and together exceed 32 KB, Alvin indexes them once — per file its size, last change, opening lines and, for its `#`/`##` headings (evenly thinned when a file has more than the index budget holds), the exact place the serving model's reading tool starts at, in that tool's own unit — and puts that index into the system prompt so the model jumps to the one section it needs instead of reading the files from the start on every turn. The index is rebuilt whenever a source file changes and cached under `~/.alvin-bot/briefings/` (owner-readable only, never in the repo). The consequence worth knowing: those headings, each file's opening lines and each file's full path now leave the machine on **every** turn of that workspace, including turns unrelated to those files and including hosted providers — previously they only went out when the model read the file itself. Add `briefing: false` to the frontmatter to switch it off; the rest of the prompt is unchanged.

### 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`:
   ```bash
   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:

```bash
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.** Agent 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

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

# AI Providers (at least one needed)
# The Agent SDK provider uses CLI auth — no key needed
GROQ_API_KEY=<key>              # Groq (fast models; speech-to-text fallback)
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 → lokal → ollama → fts5.
# lokal = semantic search inside the bot (multilingual-e5-small, ~230 MB,
# no Ollama, no key; `alvin-bot embeddings lokal` installs it). In auto mode
# without any vector provider it installs itself in the background.
# fts5 is the zero-config keyword fallback — no key needed, works for everyone.
EMBEDDINGS_PROVIDER=auto                  # auto | gemini | openai | lokal | ollama | fts5
EMBEDDINGS_LOKAL_AUTOINSTALL=true         # false = never install lokal on its own
EMBEDDINGS_LOKAL_LEERLAUF_MIN=15          # lokal: free the model's RAM after N idle minutes
OLLAMA_EMBEDDING_MODEL=nomic-embed-text   # only used for ollama provider

# Ollama on demand — the bot holds Ollama's port and starts Ollama only when a
# request actually uses it; after N idle hours it stops Ollama (RAM/GPU free).
# Works for every caller (bot, `ollama` CLI, scripts). Don't auto-start
# Ollama.app at login when this is on.
OLLAMA_ON_DEMAND=false
OLLAMA_IDLE_STOP_HOURS=4
OLLAMA_INTERNAL_PORT=11435                # where the real Ollama listens
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 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`:
   ```bash
   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`:

```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](https://github.com/WhiskeySockets/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

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

```bash
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 the Agent 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.

```bash
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.

```bash
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.

```bash
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)

```bash
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)

```bash
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](https://github.com/microsoft/OmniParser) 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:

```bash
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:

```bash
~/.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

```bash
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:

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

# v5.139.0 — tool time limits and the one switch that lifts every guard
ALVIN_SHELL_TIMEOUT_SEC=600            # Default limit for run_shell (was a fixed 30 s)
ALVIN_PYTHON_TIMEOUT_SEC=600           # Default limit for python_execute (was a fixed 60 s)
ALVIN_SHELL_TIMEOUT_MAX_SEC=1800       # Ceiling a single call may ask for via timeout_seconds
ALVIN_FREIE_HAND=1                     # Lift EVERY tool guard (command, write paths, allowlist)
```

---

## 🗺️ Roadmap

> Per-version details: see [`CHANGELOG.md`](CHANGELOG.md). The roadmap is a forward-looking summary, not a changelog.

### ✅ Recently shipped

| Version | Theme | Highlights |
|---|---|---|
| **v1.5.165.0** *(October 2026)* | Installer, `alvin-bot` command, outbox hardening | Ships 5.163.0–5.164.1 to npm. "Set up now? [Y/n]" after `curl … | bash` (Enter yes, Ctrl-D/Ctrl-C no, not asked without a terminal); launcher `~/.alvin-bot/bin/alvin-bot` starts the bundled Node (works without `node` on PATH, outside npm so updates keep it); a system Node is reused only from 22 on (not 23); the bot puts the runtime's `bin` first in its own PATH and the launchd file lists it; a re-run repairs from any terminal, also installs from before 5.165; the wizard detects a development checkout by the package location, not the working directory; four timed steps, npm noise in `~/.alvin-bot/logs/install-*.log`; runtime folder never deleted. Outbox: partial writes on a full disk lose nothing, the 1 MB startup cap counts only pending entries (hard limit 32 MB), each failed Telegram call counts once, reconnects pull forward at most every 3 s; `ALVIN_SDK_START_FRIST_MS` below 10 s counts as 10 s |
| **v1.5.164.1** *(October 2026)* | Scheduled jobs start once | After a long scheduled job, the scheduler re-reads every further job and checks it against the current time, so a job that an overlapping tick already started does not run a second time. |
| **v1.5.164.0** *(October 2026)* | Answers independent of messenger outages | A turn ends when the model is done: history, web interface and lane are free at once; replies to Telegram, WhatsApp, Slack, Discord and Signal go through a persistent outbox (order per chat, backoff 2 s to 5 min, one "delivered late" header, failed after 24 h and shown in the web interface); typing, reactions and live draft give up after 5 s and pause during an outage; updates that arrive while the bot restarts are processed instead of dropped, none twice |
| **v1.5.163.0** *(October 2026)* | Start watch and process watch | Agent SDK turns stop after 90 s without a first message from the CLI and say why (`ALVIN_SDK_START_FRIST_MS`, `0` = off, min. 10 s since 5.165.0, max. 1 h); other CLI lanes are skipped for that turn, the rest of the chain still runs; orphaned processes (ppid 1) with ≥ 90 % CPU in 6 checks in a row are reported once; opt-in stopping (`ALVIN_PROZESS_WAECHTER=an`) only for accidental agent-shell leftovers (no `setsid`/`nohup`, starting shell gone), identity re-checked before each signal; default `melden`, `aus` turns it off |
| **v1.5.162.3** *(October 2026)* | Background agents keep their helpers | Helpers started by a background agent may run up to 4 h after its last turn (was 10 min, `ALVIN_DISPATCH_BG_WAIT_MS`); the agent is told to wait for them and to check real state before reporting; `/restart` and `/update` suggest English modes |
| **v1.5.162.2** *(October 2026)* | `/permissions` | The permissions command is English (`/permissions`, areas `files`, `full-disk`, `automation`, `accessibility`, `screen`) and also reports Accessibility |
| **v1.5.162.1** *(October 2026)* | Permissions in one go | `/rechte` (now `/permissions`) triggers every macOS folder, drive and System Events prompt at once and reports per item (works, dialog waiting, denied with where to allow it); `open <area>` opens Full Disk Access, Automation, Accessibility, Screen Recording or Files and Folders; the folder-access watch points to it; model menu marks entries that follow the default model |
| **v1.5.162.0** *(October 2026)* | Agent on your API key, readable model menu | Lanes can run the full agent billed to a pay-per-use API key (a default lane and three model tiers), separate from the subscription; with a key the fallback chain tries the API lane first; background agents, jobs, tools and terminal no longer inherit the key; direct API models reachable again; scheduled jobs can dispatch background agents; model menu wraps long names and has touch-sized rows |
| **v1.5.161.2** *(October 2026)* | Scheduled jobs: safe from an unreadable job file, folder-access watch | After reading an unparsable cron-jobs.json the bot saves nothing (creating/changing a job fails clearly, the scheduler skips the tick, a notification after two minutes); `cron-manage.js` stops instead of overwriting and writes atomically; results shortened without splitting emojis; a watch notifies once when macOS blocks a folder the active jobs use and once when it works again |
| **v1.5.161.1** *(October 2026)* | Alvin Live: one connection per call | A reconnect after a dropped connection only runs while that connection is still the current one, so hanging up and calling again during the wait no longer opens a second connection (second voice session on the server); events of an earlier connection no longer affect the running call; hanging up while connecting closes the connection, and a connection that still opens afterwards closes itself; mute unchanged |
| **v1.5.161.0** *(October 2026)* | Alvin Live: mute without hanging up | Mute button next to the call button and the M key; while muted no audio reaches the voice model (also enforced on the server, whatever the browser sends), Alvin keeps working and reporting results, and the transcript marks mute and unmute |
| **v1.5.160.2** *(October 2026)* | Documentation in vendor-neutral words | README, handbook, Docker and security guides, `llms.txt`, configuration templates, package description and keywords describe the agent runtime in neutral terms; provider ids, environment variables, commands and file names unchanged; third-party attributions unchanged in THIRD-PARTY-NOTICES.md; one contact address (alvbln7@gmail.com) in licence, package details and docs, Windows notes inside the README; a test keeps the shipped documentation that way. No capability removed. |
| **v1.5.160.1** *(October 2026)* | Mid-reply messages with agents running | A turn that started fresh because background agents were pending is no longer taken over by the next message (steered or queued instead); a taken-over turn never sends the empty-reply fallback, even when its stream ends without an error; agent results on Agent SDK lanes arrive without the false "summary unavailable" note, logged as info instead of a warning |
| **v1.5.160.0** *(October 2026)* | Alvin Live: choose the working model | Live setting "Alvin's model for tasks" pins the live lanes (`live`, `live-<workspace>`) to a model of your choice with the fallback order intact; task cards reconcile with the bot after hang-up and reload; "New session" discards parked results (kept in the archived transcript, late agent results now logged too); media store waits for a discarded file to close before deleting it |
| **v1.5.159.0** *(October 2026)* | Alvin Live | Voice calls in the web interface with Gemini Live as the voice and Alvin as the brain (non-blocking `ask_alvin` into lanes, status and stop from real task state, background-agent results told later, parked after hang-up); key setup with a live check; live models from Google, newest by default; 30 voices with preview; emotion on by default; reserved `live` lane plus `live-<workspace>` lanes, `liveThemen:` routing hints; no Telegram posts for voice tasks; exact cost per live session from `usageMetadata` and the daily-read price list; echo filter with playback reference and hard local stop; `Permissions-Policy: microphone=(self)`; first load smaller than 5.158.0 |
| **v1.5.158.0** *(October 2026)* | Memory search without Ollama, Ollama on demand, server fixes | `EMBEDDINGS_PROVIDER=lokal` (multilingual-e5-small via onnxruntime-node in a child process, idle exit after 15 min, pinned and SHA-256-checked files, auto-install when no vector provider, searches don't wait on a running full index); `OLLAMA_ON_DEMAND` wake proxy on Ollama's port (starts on use, read-only listings from cache, idle stop after 4 h, adopts a running instance, never stops a foreign one); doctor reads env config, pre-flight measures `ALVIN_DATA_DIR`, Web-UI-only without Telegram watch; Docker guide: Agent SDK sign-in inside a container |
| **v1.5.157.1** *(October 2026)* | Maintenance page loads again, `<invoke>` tool calls run | Each of the page's requests runs on its own with a 20-second limit and shows a failure as a finding or a note; the backup list skips unreadable entries and does not follow symlinks; the server answers a failing API route with a 500 JSON error; a message that is exactly one `<invoke>` call (optionally inside `<function_calls>`) to an offered tool runs like a structured call, anything else stays text; first-load size not above 5.157.0 |
| **v1.5.157.0** *(October 2026)* | Memory visibility and a faster index | Built-in private prefixes (`memory/privat/`, dated topic notes), `privateQuellen: *`, grants at least as specific as the private prefix; extracted facts per origin (`memory/privat/`, `memory/ws-<workspace>/`, lane folder), never `MEMORY.md`; index covers `projects/`, `research/`, `privat/`, `ws-*`, lane subfolders (lane files down to two subfolder levels) and drops deleted files with read and 5 % (at least one) guards; `datierte-notizen` grant; removing a lane in Telegram and the web UI: archive preselected (`memory/archiv/`, main only), delete for good after a second confirmation, a web delete without a choice archives; deleting a user deletes its lanes and lane archives for good; memory page with every notes folder, the lane archive and workspace grants, saving there works again; `PRIVATE_QUELLEN` from the env editor without restart; vectors in RAM with reload on change, identical vectors counted once, filters before top-k including the keyword fallback; memory-folder line in prompts, `gedaechtnis:` per workspace, dispatched agents start in the session's directory; doctor shows private prefixes and reports stray `memory` folders; `ALVIN_HUB_DIR` |
| **v1.5.156.2** *(October 2026)* | Private memory stays where it belongs | `PRIVATE_QUELLEN` + workspace `privateQuellen:` decide which lane sees project notes, legal files and other private sources; one rule for project notes, recall, `/recall`, asset overview and `alvin-bot search`; project notes load by name |
| **v1.5.156.1** *(October 2026)* | Memory index catches up again with Ollama | Index building retries a hiccup between Ollama and its model runner, server errors and dropped connections up to four times instead of discarding the whole run; a real error fails at once; the search inside a turn keeps a single attempt |
| **v1.5.156.0** *(September 2026)* | Files the bot sends show up in the Web UI | Every file sent to Telegram also appears in the lane column of the turn that produced it (the main lane also shows background agents and scheduled jobs) and in the web chat for web-chat turns; images inline at their final size, other files as cards with a download link; copies kept 30 days or up to 1 GB (`MEDIEN_MAX_TAGE`, `MEDIEN_MAX_BYTES`, off with `MEDIEN_AKTIV=false`); agents and scheduled jobs send through the running bot with `curl -K "$ALVIN_MEDIEN_CURLRC"`, plus `send-file` in the CLI; no new model tool, system prompt unchanged |
| **v1.5.155.0** *(September 2026)* | Web interface comfort, restart warnings | New-session button in the chat header (reset like `/new`; stop and restart when a reply is running; same question from the palette and the main lane); collapsible desktop sidebar (icon rail, remembered, drawn at the chosen width from the first frame); header pill for running jobs, replies and agents plus a ticker for jobs due within five minutes; warning on every interactive restart path with restart anyway / when idle / cancel, direct forms `/restart jetzt\|frei\|abbrechen`, `/update jetzt\|frei`, `/tts <provider> jetzt\|frei`, `RESTART_WHEN_IDLE_MAX_MIN`; lanes list view, loaded on first use; Markdown in the web UI that renders nested lists, more list forms, e-mail addresses and formatted link text; sidebar footer buttons for theme and sound as icons with tooltips; `/pp` and `/pro_prompting` described in English like all other commands; web files delivered without source comments. No capability removed. |
| **v1.5.154.0** *(September 2026)* | Web UI shows formatted replies properly | Replies in the lanes and on the chat page render Markdown as intended — tables, headings, block quotes, horizontal lines, lists and links — while code stays exactly as written and emphasis applies only where it was meant, so `3 * 4 * 5` stays a calculation; the renderer stays fast on long replies, including very long single lines. Command replies (`/status`, `/help`, `/lane`) read as plain text with their line breaks, without leftover messenger formatting. A lane with agents working in the background says so in words, its status light gets a clearer ring, and it learns immediately when an agent starts or finishes; hovering shows what each agent is doing. A reply stopped halfway keeps its visible part in the history and later messages appear below it; a message sent while a reply is running is kept in the history too, and the lane refreshes right after compaction. Photo, document, voice and video turns appear in the lane history on every provider. The lane badge names the model that answered, with the provider name always readable. Link previews of pages not encoded in UTF-8 show the correct characters, and long responses from command-line providers, tools and speech transcription keep accents and emoji intact; shortened previews no longer cut an emoji in half. Finished background agents deliver their full result right away, and the note in front of an untidied result carries no stray formatting characters. The settings pages handle names and messages with unusual characters more strictly, links in replies follow stricter rules, editing the fallback order always keeps the primary provider, and custom-model entries wrap on phone screens. |
| **v1.5.153.0** *(September 2026)* | Earlier messages carry the time they were sent | Every history message handed to an OpenAI-compatible model (Ollama, Groq, OpenRouter, local servers) now starts with a bracketed timestamp in the bot's timezone, in the same form as `now` in the date anchor — `[2026-09-20T20:28+02:00]` — and the system prompt explains once where it comes from and that the model must never write one itself. Before, the history was bare text and a smaller model guessed the distance: GLM 5.3 Flash called a finding it had made nine minutes earlier "from yesterday". The current message is not stamped; entries stored before v5.86 have no timestamp and go unchanged; a history without stamps sends exactly the prompt it did before; the Agent SDK path keeps its own transcript and is untouched. Compaction names the time window it summarised and shows the summariser each message's stamp, so daily logs and extracted facts record *when*. Daily memory logs, "Today's Log" / "Yesterday's Log", the sibling-lane window and the `## Auto-extracted (date)` heading now use the local date of the bot's timezone instead of the UTC date — between local midnight and 02:00 in summer time an entry used to land in yesterday's file with a local wall-clock time, which is exactly the shape that makes a model say "gestern" about a note half an hour old. Existing files are not renamed. |
| **v1.5.152.0** *(September 2026)* | A message can ask for a briefing before it runs | `/pp <request>` has the bot write a short briefing for itself before the request runs — goal, the context it already knows, the constraints from the message quoted verbatim, output format, done-criterion, and every open question turned into a named assumption — appended beneath the unchanged original, with one preview line in the reply. The briefing is validated in code, not merely asked for in the prompt: a constraint that is not a word-aligned verbatim quote of the message is dropped, so is one that loses a negation inside a three-word window; a control character or line break anywhere rejects the whole briefing; role-play, step-by-step scaffolds, shouting and numeric length caps are refused, and the rendered block is capped. Fail-open is total: a slow, failing or invalid rewriter leaves the message exactly as typed, under a six-second deadline enforced by the bot (`Promise.race` against its own timer) rather than trusted to the provider, and repeated deadline misses pause the feature for that session and tell the operator once. `/pro_prompting auto on` extends this to every task-shaped message: off by default, persisted across restarts, and excluded — as a hard rule that `/pp` cannot override — for confirmations, replies to the bot's own questions, steering notes into a running turn, synthetic turns, cron jobs, autopilot turns, continuations and any forwarded or quoted third-party text, so distilled foreign content can never re-enter the prompt outside its fence. The rewriter is a second, small model, by default from a different vendor than the executor (`/pro_prompting status` names it, `PRO_PROMPTING_MODEL` changes it); it sees the message text and nothing else — no files, no history, no system prompt — and never the SDK executor, which is no longer used as a fallback. Fifteen documented technique entries ship in the package, each with the primary source it was checked against, indexed per model family; `/pro_prompting add <text>` adds your own. Three kill switches: `ALVIN_PRO_PROMPTING=off` at start, the file `~/.alvin-bot/pro-prompting/AUS` at any time without a restart (`/pro_prompting off --alle`, owner only), and the per-session switch. The briefing is kept out of the model's history as its own entry kind, so no model ever reads it back as the user's words. Also in this release: the short-call path (lane titles, compaction summaries, memory extraction) now passes a reasoning level to thinking models, which previously spent the whole output budget thinking and returned nothing visible, with the same refusal fallback the main path uses; and the Groq preset, which pointed at a retired model, names a current one. With the prefix absent and the automatic mode off, the prompt handed to the model is byte-identical to 5.151.0, pinned by tests on the Telegram, platform and web paths. |
| **v1.5.151.0** *(September 2026)* | Self-restart detection matches this process only | `isSelfRestartCommand` compares the full launchd label (optional `.plist`, boundary behind it) instead of the `com.alvinbot` prefix, in the `launchctl` **and** the `pkill` form, so neighbouring services are reachable again; a `pkill -f` pattern is matched against this process's own command line, read from the process table rather than rebuilt from the symlink-resolved interpreter path, while the package name as a word of its own and the full label are recognised independently of the install path. Every `pkill`/`killall` of a line is examined, not just the first. `pkill` arguments are parsed as `pkill` parses them, case included: an option's own value (`-u`, `-P`, `-t`, `-F`, …) is no longer a pattern, `-F` is not `-f`, a signal name (`-INT`, `-QUIT`, `-STOP`, `-CONT`, `-HUP`, `-TSTP`) no longer swallows the `-f` behind it, a quoted multi-word pattern stays one pattern, and `--full` counts as `-f`. A foreign pattern is never compiled — its literal pieces are matched in order, `^`/`$` respected, which cannot backtrack and cannot stall the synchronous tool path. The catastrophic baseline judges the targets of the `rm` that runs rather than the whole line (no more refusals from a stray ` / `), covering `rm -rf /*`, `//`, `"/"`, `'/'`, `/bin/rm -rf /`, `rm -rf ~/`, `rm -rf $HOME`, the long-form flags and `cd <protected> && rm -rf *`, and keeping the deletions that stand behind an assignment, a pass-through, an arbitrary executor (`watch`, `strace`, `docker exec`, `eval`, …), `xargs`/`-exec` or a line continuation; `mkfs` must stand as the command word, and the text inside `sh -c`/`bash -lc`/`su -c`/`ssh <host>` is examined as a command of its own while every other wrapper falls under the unknown-leading-word rule, so a wrapper hides neither the formatter nor a root deletion. Shell grammar in front of the command (`( … )`, `{ … ; }`, `!`, `$( … )`, a leading redirection) no longer makes a segment look like prose, a pipe into a bare shell executes what the left side prints, an `xargs` replacement string is not a target of its own, and a separator inside quotes no longer splits a command — while a quote that never closes falls back to splitting at every separator, so an apostrophe in prose cannot hide a deletion behind it. A path behind an `ssh <host>` is on another machine and is no longer judged by the list that protects this one, while the catastrophic baseline still sees it; the agent CLI's settings folder joins the protected directories. `newfs` counts as a formatter with `mkfs`. Intercepted commands are logged with source, working directory, rule and outcome, and the reply states the command was not executed and names the piece that matched. Measured over 6,411 real commands plus 31 constructed ones: with the operator opt-out set, exactly two commands the previous release allowed are refused — a root deletion on a remote host, and `newfs`, which sits in the baseline that no mode releases (formatting a stick needs `ALVIN_FREIE_HAND`). In the default mode eight more, six of them another spelling of a target that release already refused plainly (`"$HOME"/…`, `${HOME}/…`, `~/'Projects'`, `bash -c 'rm -rf /var/tmp/build'`) and two of them the agent CLI's settings folder; the opt-out releases all eight. Forty commands from that history are no longer refused. Speed, both versions measured alternately in one process: 28.9 ms against 29.6 ms over the corpus, p50 1.33 µs against 1.67 µs — the direction depends on the corpus (1.12× slower on short lines, 0.91× on medium), and all of it is fractions of a microsecond against a process start measured in milliseconds. `killall node` and `pkill -x node` now restart the bot instead of killing it, `pkill` operands are read without the words behind them (`2>/dev/null` no longer displaces the pattern), and the verb is recognised behind a path, a quote or a bracket. Applies to the shell tool and custom tools; the agent-SDK path and scheduled shell jobs are not covered. |
| **v1.5.150.1** *(September 2026)* | Cron retry budget on every provider | `isMaxTurnsError` also recognises the generic tool loop's "Max tool call rounds reached", so a scheduled AI job that stopped at its round limit on GLM, Ollama or another OpenAI-compatible provider is retried with the doubled budget (300→600) like on the Agent SDK; the delivery says "stopped at turn limit". No capability removed. |
| **v1.5.150.0** *(September 2026)* | Lanes: nothing typed is lost | Mid-turn messages routed by the reader of the running turn's steering channel (set per chain attempt, cleared when the stream ends) instead of the global provider; queued messages run as their own turn when the turn ends (not after a stop or takeover, never into another lane); unread steered messages carried into the queue; lane:ack reports the handler's decision; per-lane stop (`lane:stop`, same step as `/stopall` per lane) with confirmation, enabled only when something runs; headers in three fixed rows with fixed line heights, touch targets 29 px, autopilot badge never shortened, model badge keeps its symbol; eraser icon for reset; Lucide licence shipped. No capability removed. |
| **v1.5.149.1** *(September 2026)* | Audit cross-check | Lean prompt stops after its four core blocks instead of building and cutting; literal NUL separators replaced by escapes in five files (git showed them as binary), guarded by a test; hourly snapshot records the loop watcher's evaluated windows, highest window p99 and maximum; startup and daily snapshots carry the process ID. No capability removed. |
| **v1.5.149.0** *(September 2026)* | The audit, finished | Version shown in the connection line (one WebSocket frame per connection); lane rebuild bundled per lane, reader position kept on rebuild, turn end and error line, no fade-in on rebuild; chat storage quota reported, newest 200 messages restored with the rest on demand; reindex replaces after embedding in one transaction, mtime taken before the read, unchanged vectors reused, 2,000-character sections, base64 excluded, short tails kept, one-time cleanup of the `memory/MEMORY.md` twin and oversized sections; extractor and UI saves trigger a reindex; daily log appended; availability expiry counted from after the probe, one probe per Agent SDK account, heartbeat counts the result; Telegram turns release the session before cleanup; video, setup check, disk space and PM2 check off the main thread; status routes report without quarantining; WebSocket frames capped at the upload limit; Inter self-hosted; Ollama cloud context windows measured. No capability removed. |
| **v1.5.148.0** *(September 2026)* | Search that actually searches | `web_search` escalates to a real browser when the HTTP routes hit a captcha: isolated `--session`, closed afterwards without `--all`, up to three reads to survive the engine's own redirect, destination URLs decoded out of the redirect parameter; PATH lookup shared with the startup tool scan; the fallback message no longer offers the browser as an untried idea. No capability removed. |
| **v1.5.147.0** *(September 2026)* | Four reported faults + audit release C | Read-aloud: player woken inside the click (4,514 ms → 8 ms to `play()`), mp3 instead of Ogg/Opus, `.wav` MIME type, text indents around the button; turn sounds: leading-edge lane-state push (a sub-second turn was invisible), busy derived from running turns, minimum gap defers instead of discarding, one lane state per fresh connection, the settings-ignoring 800 Hz beep removed; web search uses `BRAVE_SEARCH_API_KEY` (header file, never the command line) and the captcha message names the browser as step one; `[zug-kosten]`, `[sdk-start]`, cached tokens and window saturation logged; tool scan without processes; cron parses its job file once per tick and complains once per version; vector scan without text; provider family from the base URL; WAL size limit + VACUUM. No capability removed. |
| **v1.5.146.0** *(September 2026)* | Wire bytes + a UTF-8 data bug | Request bodies buffered as bytes (chunk-boundary character loss fixed, 64 MB cap, 413 instead of a dropped connection); content-hash ETag + 304 + gzip for static files and API JSON; `lastResult` dropped from the cron list; v1 `text` frame carries the full state only when deltas cannot reconstruct it; `/api/terminal` and `/api/mcp/discover` moved off the main thread; cleanup loop started in both modes with error logging and orphaned-marker removal; `MEMORY.md` indexed once. No capability removed. |
| **v1.5.145.0** *(September 2026)* | Throttle removed, probes off the main thread | launchd `ProcessType` Background→Interactive (PRI 4→20, 3.1–5.6× on all local work, inherited by every child process); `detectSupertonicEnvAsync()` runs its five probes concurrently off-thread, remembers only a positive verdict (invalidated by the venv Python's mtime, never by a clock), distinguishes a missed deadline from a missing package, single-flight; maintenance poll gated to the visible page; process-manager detection memoised; one reused AudioContext for the turn chime. No capability removed. |
| **v1.5.144.2** *(September 2026)* | Readiness probe memoised | `synthesize()` skips `detectSupertonicEnv()` after a success and re-probes after a failure; a synthesis carries a loop breadcrumb. Same path serves Telegram voice replies. No capability removed. |
| **v1.5.144.1** *(September 2026)* | Non-blocking DB check | The boot-time `quick_check` moves to a worker thread (`preflight-sqlite-worker.ts`): same check, same verdict, main thread never waits; the report says "running in background" after 2.5 s and the verdict follows as its own line (critical → owner message). Watcher captures that fail are logged with a reason. Read-aloud cache: all-async FS, trim after reply, no `:has()`. No capability removed. |
| **v1.5.144.0** *(September 2026)* | Thinking/writing cues, read-aloud | `Thinking` and `Writing` join the sound cues (lane-state start, first delta), each switchable with a preview. Every reply gets a top-left play button: `POST /api/vorlesen` synthesizes with the configured TTS provider into a 60 MB LRU cache keyed by text hash, `GET /api/vorlesen/<id>` streams it; button hideable under Settings. No capability removed. |
| **v1.5.143.0** *(September 2026)* | Version on the login screen, v1 labelling | The login page shows the running version via a public `GET /api/version`, and human-facing surfaces (`/version`, `/status`, the TUI, the model's runtime header, the login screen) read `v1.5.143.0` while npm, the updater and every comparison keep the package number `5.143.0`. A test fails the build if the display string reaches a comparing path. No capability removed. |
| **v5.142.3** *(September 2026)* | Stall stacks | A watcher thread reads the main thread's heartbeat and captures its native stack with `sample` after three seconds of silence, writing the deepest frames to `loop-stall.log`; breadcrumbs at startup phases, turn start and plugin tools. No capability removed. |
| **v5.142.2** *(September 2026)* | No more idle heat | The sidebar's connected dot animated its shadow, forcing a repaint every frame on every page (26.6 % of a core at idle, measured); all keyframes now move only opacity/transform, the dot pulses three times then rests, `prefers-reduced-motion` disables the rest, and a test refuses per-frame repaints. Idle: 0.5 %. No capability removed. |
| **v5.142.1** *(September 2026)* | Sound cues on iOS, per-cue switches | The audio context is no longer suspended when idle (iOS would not resume it outside a tap, silencing every server-driven cue); it is created on the first tap and woken on return from the background. Each of the eleven cues has its own on/off switch with a preview under Settings. No capability removed. |
| **v5.142.0** *(September 2026)* | Sound cues | Eleven short synthetic tones in the web interface — reply, agent start/done, autopilot on/run/run-without-news/off, error, provider switch, notice — synthesized on the spot with Web Audio (no files, nothing idle, cooldowns). Derived from one comparison of the lane state the server already pushes. On/off, volume and previews under Settings; a Sound button in the sidebar. No capability removed. |
| **v5.141.0** *(September 2026)* | Web search fails honestly | `web_search` no longer crashes on an empty DuckDuckGo reply ("Unexpected end of JSON input"); the fallback drops `grep -oP` (absent on macOS) for a JavaScript parser that also resolves redirect links; a bot challenge is reported as such, not as "no results". The system doctor's empty-`.env` warning names the keys and becomes informational. No capability removed. |
| **v5.140.0** *(September 2026)* | Workspaces can be removed | A Remove button on every workspace card and `/workspace rm <name>` on Telegram, both naming what is bound to it before anything happens (lanes, sessions, active users — the list comes from the server). Removing releases the lane bindings, the sessions' name and working directory, and each user's active pointer, so nothing keeps running in the wrong directory unannounced. `default` cannot be removed; working directory, messages and lanes stay. New endpoint `POST /api/workspaces/delete` with a dry run. No capability removed. |
| **v5.139.0** *(September 2026)* | Nothing blocks, nothing freezes | Everything volatile moved out of the recorded system prompt into a per-turn `<turn_context>`, so a long session stops answering with a frozen clock and a stale agent ledger. Quota exhaustion is recognised per account, locks it until its reset and answers on the next chain link (`/kontingent`). Shell and Python default to 600 s (up to 1800 per call). `read_file` and `list_directory` are async with a budget and recognise iCloud placeholders; a loop watchdog records stalls with tool and path class. Dispatched agents run with the chat's permissions. Content fencing returns the tool's own shape — it had been rejected 248 times in a week — and now also covers WebFetch, WebSearch, MCP and uploads. `ALVIN_FREIE_HAND=1` lifts every tool guard. Summariser and fact extractor use the light one-shot path and run after the turn. Cron page gains filters and bulk actions. No capability removed. |
| **v5.138.0** *(September 2026)* | Autopilot off means off | Jobs and background agents an autopilot run starts remember the run. `/autopilot off`, a run ending at your limit, and `/lane rm` list what is still running, with buttons to pause the jobs, stop the agents or keep them; nothing stops without a tap and jobs are paused, not deleted. A follow-up after the run has ended is a normal turn. Every tool a turn starts sees its origin (`ALVIN_ORIGIN_*`), `scripts/cron-manage.js add` stores it, and `/cron` and the web job card show it. No capability removed. |
| **v5.137.1** *(September 2026)* | Lane titles after a restart | Clearing a lane's name titles it from its existing conversation right away, also directly after a restart. |
| **v5.137.0** *(September 2026)* | Lane titles, light and stable | Automatic lane titles return: made by the lane's own model over its lightest route, only after the answer and only when the topic really changes; returning to an earlier topic restores its title without a call. Visible in the web board and in Telegram's `/lanes`; a typed name always wins; `LANE_TITLES=off` turns them off. |
| **v5.136.0** *(September 2026)* | The Agent SDK's model and effort, visible and controllable | The vendor's top tier is the Agent SDK's default model and follows new releases on its own. `/provider` sets the Agent SDK's model for everything without its own; `/model` is lane-only and says when a provider has just one model. Scheduled AI jobs carry their own effort (medium by default), one effort rule covers every kind of message, and background agents follow the effort of their turn. Model choices, including the web chat's header, name what the Agent SDK provider runs today. |
| **v5.135.1** *(September 2026)* | Nonblocking tool subprocesses | Shell, Python, web, native-image and browser helper processes no longer freeze the live tool event loop. Existing permissions, native images and output semantics are retained; owned subprocesses support bounded cancellation. |
| **v5.135.0** *(September 2026)* | Consistent model context, guarded tools and bounded perception | Lane/model context survives background delivery, media fallback and empty-SDK retries. Tool rights are enforced at execution; explicit synthetic capability probes use route-qualified evidence. Native images stay direct; optional local helpers have conservative resource gates and document evidence keeps page/sheet and truncation information. See the changelog for intentional helper restrictions and validation limits. |
| **v5.134.0** *(September 2026)* | Each lane keeps its own provider and model | Every lane, including main, selects and persists its own provider and model. `/model` addresses that lane; Codex CLI reads the account's available model catalogue. Text, media, WebUI and scheduled runs respect these choices, fallback providers do not inherit another provider's model ID, and model picker buttons remain bound to their original lane and provider. |
| **v5.133.0** *(September 2026)* | The tool path is measured, eyes for models without vision, documents as text | A local model is measured once (native tool calls, text protocol, read-then-write chain) on a user's turn, with a small tool catalogue, and afterwards takes the simplest path it passed; a result that never got an answer is not stored, a stored one applies only to the local Ollama lane, and results live in `faehigkeiten.json` beside the registry. `/status` and `doctor` show `🖐 Hands:`, `/model test` re-measures, `WERKZEUGWEG` forces a path, `FAEHIGKEITSPROBE=off` skips the measurement; the plain loop's round-0 broker is gone, so `OFFLINE_STRUCTURED_TOOLS` has no effect, and Ollama cloud tags are recognised as `:cloud` and `-cloud`. Eyes: layer 0 macOS Vision framework, layer 1 a local vision model in Ollama (cloud-proxied models skipped), fenced as untrusted; `read_image` takes a question, `look_again` asks about the session's last image, also inside the harness; `AUGEN_CLOUD` is reserved for the still-empty cloud layer. Documents: PDF, DOCX, PPTX and XLSX become text on upload and through the new `read_document` tool (paged by offset), read on macOS with PDFKit and Vision OCR before `pdftotext`/`pypdf`/`pdftoppm`, DOCX through `textutil`. Harness: an unanswering model yields an error instead of an echo, facts travel between steps, an over-large task continues in the plain tool loop of the same turn, budgets raised to 32 steps / 30 min via `OFFLINE_LOOP_MAX_STEPS` and `OFFLINE_LOOP_MAX_SECONDS`. Operational 🔬 notices are status lines and never the answer; temporary files have one directory, settable with `ALVIN_TMP_DIR`. No capability removed. |
| **v5.132.1** *(September 2026)* | Correction release: saved values survive the restart, previews stay on the open internet, autopilot "on" completes | `.env` values written by the setup wizard, `/setup key`, the environment editor and `alvin-bot setup` are stored as dotenv reads them back — a `#`, a space or a quote no longer truncates a password or key — and the web UI, the TUI and the settings page read with the same parser. Link previews use the shared network guard (plus carrier-grade NAT) and connect to the address they checked, with all resolved addresses available to the socket. `read_image` delivers real PNG bytes after a resize. Autopilot `on`: the loud mode sees its ending, a failed watch keeps watching, a replaced run's turn is not booked on its successor, the end marker tolerates surrounding punctuation and Markdown, and `on budget 5` / `on laut` / `on every 30m` / `on max 10` set what they say. Heartbeat fail-over follows the live chain and monitors providers added at runtime; a background result arrives as capped text when its upload fails, waiting out a rate limit once; a file sends without a caption; `$` sequences survive Iterate. No capability removed. |
| **v5.132.0** *(September 2026)* | The web UI answers, iterates and previews — and autopilot gains an "on" mode | Every message gains two buttons: **Reply** quotes what it sits on; **Iterate** sends the bot's own result back to it to assess what is weak, incomplete or unsupported and improve only where there is something substantial, ending with exactly one honest verdict — "Improved: …" or "Nothing substantial to improve, because …"; nothing to improve is a fully valid result. Links in bot messages arrive as preview cards (title, domain, description, thumbnail) in the chat and in lanes, loaded lazily when the bubble scrolls into view, clipped to the card, silent on any failure — the link keeps working. `autopilot on` turns a lane into a self-directed run: it derives its task from the lane's context, works until done, announces the hand-off ("task complete — I'll keep watching") instead of ending in silence, then watches; a typed message in the lane marks the watch as fresh and prompts a rate-limited look-around, while the run's own turns never do. The status line shows `on · working/watching`, and the lanes dashboard shows the phase on the badge. No capability removed. |
| **v5.131.0** *(September 2026)* | Images reach the model as images, and foreign text no longer kills a reply | New `read_image` tool: local PNG/JPEG/WebP/GIF travel as an image, format detected from content, oversized ones downscaled instead of rejected — and a tool result's image survives the redirect to GLM/OpenRouter/Ollama as its own message instead of arriving as a "not forwarded" note; MCP clients see real image content. Telegram replies quoting foreign text (group titles, reminder texts, job names, model tags) died whole on a single underscore or ampersand, silently wherever the bot only logged; all such spots escape the text now, and the ollama model-card buttons take the same routes as the typed commands. The dashboard shows a server's `ok:false` as a rejection with its reason, writes its `.env` securely, and holds its markup against untrusted text. Promoting a fallback provider is one decision everywhere — immediate, reported when rejected, one name in every display; a held chain holds for a pinned lane; custom models keep the name you gave them. Promised work arrives: no paid follow-up turn after an autopilot is switched off, no double delivery after a restart, a group dispatch follows through once, and on Slack/Discord/WhatsApp a background agent's result reaches the session history too. Attachments count as delivered only when the upload went through, with a capped text fallback otherwise. No capability removed. |
| **v5.130.0** *(September 2026)* | In an autopilot run, a finding is a task, not an offer | Autopilot runs carry a frame in the system prompt: nobody is reading along, a finding within the assignment is fixed, verified and reported as done, only the irreversible/out-of-scope/third-party spend stays undone (stated in one sentence), open points from the previous run come first. The frame is inherited by background agents dispatched from the run and by their follow-up turns; typed messages never carry it. A run that still ends with a question or an offer is followed up exactly once in the same run. No capability removed. |
| **v5.129.0** *(September 2026)* | A background agent's result reaches the lane it was started from | The default Telegram delivery path for background-agent results sent the summary to Telegram only; the lane's history — what the web dashboard renders — got a 400-character note cut mid-sentence. Both paths now write the same entries (status line, summary, attribution note) in the same order. The completion note no longer claims a delivery and its excerpt ends at a sentence boundary. A missing workspace folder is caught before a background agent is started (clear message instead of an unhandled exception), and a child process that cannot start is reported as a failed agent with its reason. No capability removed. |
| **v5.128.0** *(September 2026)* | Model names are looked up, not remembered | Agent SDK and OpenAI model lists come from the live catalogues instead of the source code: your API key, your signed-in agent CLI via the Agent SDK (no key, no tokens — the list the CLI's own `/model` shows, including what each alias resolves to for your account), or OpenRouter's public catalogue. Cached for six hours in memory and on disk, refreshed in the background on use, never on a schedule; a source that does not answer is skipped and no page waits on it. The tier aliases keep working and show their resolution everywhere (`/model`, `/status`, dashboard header and cards). New `openai-latest` preset runs the newest GPT flagship at start (`OPENAI_MODEL` still pins); the OpenAI list is filtered by what a model is, so every generation appears. Codex CLI's neutral default follows the directory too. `MODEL_DIRECTORY=off` disables the lookups. No capability removed. |
| **v5.127.0** *(September 2026)* | Voice is transcribed on your own machine, and speech errors stop pretending to be noise | A local Whisper handles voice messages when one is installed — no key, no network, no third party; measured 21× real time on an Apple M4, so a five-minute message costs about eleven seconds. Groq stays as the fallback and every switch is logged with its reason, including the case where the binary is present but its model file is missing, which previously looked identical to "nothing installed". Separately: every error from the speech API had been collapsed into an empty string, which the caller reported as "could not understand the voice message" — an expired key, a rate limit and a rejected file were indistinguishable from someone mumbling. They now report what actually happened, and a request that hangs is cut off instead of never answering. `/autopilot` and `/about` are suggested in the lane composer again; both were reachable by typing but hidden from the list. No capability removed. |
| **v5.126.0** *(September 2026)* | The autopilot stops when you say so, and the terms are where you can read them | `/autopilot <task…>` applies to the lane you are standing in and runs until you switch it off. The previous release cut a run off after 24 runs or $5; both are gone, because they were an assumption about someone else's circumstances. Limits are yours to set — `every 30m`, `max 50`, `budget 5` — and switches are read only at the end of the line, so a task like "check the filing every 45 min" stays a task. Three identical answers send one notice instead of ending the run: usually that means stuck, sometimes legitimately waiting, and only a person can tell. New `/about` names what the software does, whose terms govern which part, and that use is at your own risk; the same wording appears before the setup wizard writes anything, where it can be declined. THIRD-PARTY-NOTICES.md ships in the package and names every component, including the proprietary agent SDK and two copyleft dependencies. No capability removed. |
| **v5.125.0** *(September 2026)* | A lane can work on by itself, and stops on its own eleven ways | Autopilot per lane: one run every two hours, at most 24, stops at $5 — and sooner when the same answer returns three times, which is the likeliest way to spend the budget on nothing. The cap counts the run, not the day (a daily counter resets at midnight and would allow twice the agreed amount over two days); an unreadable spend halts instead of passing; the state lives on disk so a restart cannot reset the counter; the clock hangs off the last run rather than process start, so a restart loop cannot become a spending spree; twelve hours of sleep are worth one run, not six; a working lane is never poked; a failed run still counts. Quiet by default: runs appear in the lane view, the chat gets start, end and problems. `main` cannot run on autopilot and there is no global switch. No capability removed. |
| **v5.124.0** *(September 2026)* | The Agent SDK lane runs on any OpenAI-compatible provider | A local translator accepts the Agent SDK's native protocol and forwards it as `chat/completions` — tool schemas washed, tool results reshaped, the stream translated by a state machine with its own block index. Both answer paths make their decisions in one place (four of five cases had already drifted apart). A rejected request gets one adjusted retry; the target model's context window is converted into the scale the client thinks in, and a request that no longer fits is refused before it is paid for. Attached documents reach the model or say why they did not, instead of vanishing. An error mid-stream is no longer swallowed. No capability removed. |
| **v5.123.0** *(September 2026)* | No clock runs over a working turn any more | The round limit's replacement — a sixty-minute budget — is off by default: it was the same limit in different clothing. What ends a turn instead is a distinction rather than a threshold: the person at the wrap-up button, a line gone silent, or the standstill watch when a loop demonstrably repeats itself. Scheduled jobs and the detached sub-agent keep a limit on purpose, because nobody can press a button there. A round that never returns no longer holds the turn forever, and the wrap-up button now works on every surface. No capability removed. |
| **v5.122.0** *(September 2026)* | A lane title says what the lane is about, not what it read | Titles are drawn from what the conversation actually turns on rather than from any noun that passed through, so a greeting no longer inherits the name of yesterday's report. No capability removed. |
| **v5.121.0** *(September 2026)* | The Agent SDK lane runs without a vendor account | The full machinery — tools, sub-agents, project rules, streaming — served through Ollama, which speaks the Agent SDK's native protocol itself. No capability removed. |
| **v5.120.0** *(September 2026)* | Answers stream on every provider route, and a budget cut-off is named instead of hidden | Ollama, OpenRouter, Gemini and every OpenAI-compatible endpoint stream text as it is generated; the agent CLI bridge and endpoints without streaming keep their exact prior behaviour. A round that ends at the output budget is recognised, retried once with a larger budget, and otherwise delivered with an honest note instead of a silent half-sentence. `read_file` takes an `offset` so large files can be read to the end; truncation notices name the follow-up call. `/effort` reaches models that support reasoning levels, passed through unfolded, with honest display where a route cannot act on it. Logs rotate themselves after 30 days — configurable via `LOG_RETENTION_DAYS` and the Maintenance page, with an append-mode safety check before any truncation. No capability removed. |
| **v5.119.0** *(September 2026)* | The tool loop reads why a round ended, and big case files stop being dead ends | Slash-command answers in a lane survive refreshes and keep their place; a fresh lane no longer invents a title; leaked tool calls with stray tags are executed instead of shown raw. No capability removed. |
| **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's project rules file 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)* | A new flagship model + a deeper reasoning tier | The SDK vendor's newest flagship model and the deeper-than-high thinking tier it introduced were already supported by the model runtime but missing from the pickers. The flagship now appears in `/model` alongside the other tiers (Agent SDK **and** agent CLI 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 the new flagship and the latest top-tier model. 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 stale model version pins that a new top-tier release exposed: the setup wizard and API-key presets offer the current top-tier model (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 removed. |
| **v5.67** *(July 2026)* | Context-bloat guard — warn + opt-in auto-refresh | Very long sessions (days of accumulated transcript, embedded images) force the model to compress its context every few turns and it starts "forgetting" same-day details. Alvin now posts a one-line heads-up in the chat once a session crosses ~700k cumulative input-tokens (`CONTEXT_WARN_TOKENS` to tune; re-warns only after doubling; persisted across restarts; fires on text AND voice/photo/video/document). Opt-in `CONTEXT_AUTO_ROTATE_TOKENS` lets Alvin proactively start a fresh model session once the budget is consumed — recent history re-bridged, memory recall re-run, one-line notice, nothing deleted. Off by default. No capability removed. |
| **v5.66** *(July 2026)* | Workspace switching decoupled from lanes | `/workspace <name>` is a clean global context switch again: issued from inside a named lane it switches the MAIN conversation's workspace and returns you to main, leaving the lane's own binding untouched. The old in-lane behaviour silently re-bound the current lane on every switch — the lane "travelled along" — and each re-bind cut the lane's conversation thread (session anchor reset). Rebinding a lane is explicit-only: `/lane <name> in <workspace>`. Lane history and notes are tied to the lane's name, so nothing is lost either way. No capability removed. |
| **v5.65** *(July 2026)* | Workspace-shared lane memory (opt-in) | Lanes bound to the same workspace can now share what they know: add `shareLaneMemory: true` to the workspace file and sibling lanes recall each other's conversational notes, while a freshly opened lane starts with a compact briefing of its siblings' recent activity instead of blank. Strictly opt-in — the full per-lane isolation from v5.63 stays the default, and main's notes stay private to main in both directions. Also: voice/photo/video/document turns now get the same ambient memory recall as text (previously media turns ran without any semantic recall — a voice note as a lane's first message arrived context-blind). No capability removed. |
| **v5.64** *(July 2026)* | Codex (OpenAI) is a first-class model | Codex is now an always-available model choice — pick it anytime with `/provider use codex-cli`, no setup, signs in with your ChatGPT login, and degrades gracefully when it isn't installed. It always follows the **newest model + reasoning effort you've chosen in Codex** itself (no more fixed, quickly-stale version), with optional `CODEX_MODEL` / `CODEX_REASONING_EFFORT` overrides; the status line shows the real model it will run. Plus a reliability-polish round for the parallel **Lanes** feature. No capability removed. |
| **v5.63** *(July 2026)* | Lanes — parallel isolated workstreams | Run several separate conversations at the same time, each its own lane with its own memory, persona/folder and daily budget. `/lanes` dashboard, `/lane <name>` to switch/create, `@name: msg` to fire at another lane without leaving yours, per-lane workspace binding and budget caps. Lanes run truly in parallel (capped by `LANE_MAX_CONCURRENT`), all media types follow the active lane, and everything survives a restart. DM-only for now; nothing changes if you don't use lanes. No capability removed. |
| **v5.59** *(June 2026)* | New provider — the agent CLI bridge | A bundled **agent CLI bridge** provider runs the vendor's models through your local agent CLI instead of the Agent SDK (fully SDK-independent), selectable in `setup` or via `/provider`. Nothing extra to install — it uses the CLI binary that ships with the SDK dependency and updates with `/update`, preferring your own newer system install if present; the bot auto-starts/stops it like Ollama. Near-feature-parity with the SDK path: full tools, parallel **and** detached sub-agents, `/effort`, mid-task `/stop`, live `/btw` steering (+ plain mid-task messages), per-workspace overrides (incl. genuinely read-only `readonly`), `/model` tier switching. Sign in to the agent CLI to use it. No capability removed. |
| **v5.58** *(June 2026)* | Security hardening — untrusted content & platform auth | External content the bot reads (email, web pages, documents, forwarded/quoted messages, `curl`/`himalaya`/`pdftotext` output) is fenced as untrusted *data* so hidden instructions/vendor-impersonation aren't obeyed (own messages unaffected); injection heuristics flag vendor-impersonation; Slack default-denies an empty allowlist (set `SLACK_ALLOWED_USERS`) like Discord/Signal/WhatsApp; custom tools advertised with full param schema; `mcp.json` written atomically. No capability removed. |
| **v5.57** *(June 2026)* | Provider / failover / cost control | Daily budget cap now metered at the shared chokepoint so it covers **all** spend paths (web/voice/media/sub-agents/cron/OpenAI-compat), not just Telegram text (was a silent under-count → unbounded overspend); manual `/provider` switch is authoritative after a failover (no silent revert); web switch routed through the readiness/persist path; `/fallback` reorder applies live; Agent SDK structured-error classification (rate-limit/billing/auth/max-turns) instead of text-only sniffing. No capability removed. |
| **v5.56** *(June 2026)* | Reliability hardening round | A malformed `mcp.json` (empty `{}` / desktop-client `mcpServers` shape) no longer silently bricks startup — MCP degrades, the alias is accepted; `/cancel`·`/stopall` of a pending background agent no longer wedges the session into lost continuity; leaner long-uptime resource use (one-shot skill watchers, swept rate-limit buckets, closed CDP fallback); sturdier writes (atomic background-agent state, best-effort usage stats, coalesced re-index). No capability removed. |
| **v5.55** *(June 2026)* | Custom tools fully opt-in | Fresh installs no longer seed an active `tools.md` from the bundled example through *any* setup path (`setup`, first-boot seeding) — setup shows an opt-in hint instead; existing `tools.md` files are never touched. Completes the round-3 intent across all install paths. No capability removed. |
| **v5.53** *(June 2026)* | Audit round 3 — platform access & robustness | **Per-platform allowlist (default-deny) for Discord/Signal/WhatsApp-DM** — closed an unauthenticated-shell-access gap (set the new `<PLATFORM>_ALLOWED_USERS`). Custom tools routed through the shell + SSRF guards; no auto-active TOOLS.md on fresh installs; non-Telegram group replies credential-scrubbed; WhatsApp document filename traversal fixed; corrupt `.embeddings.db` self-quarantines instead of bricking the bot; asset/memory scanners no longer follow symlinks. Telegram/Slack/self-chat + power-mode unaffected. |
| **v5.52** *(June 2026)* | Audit hardening round 2 | Cross-site (CSRF) guard on the dashboard's sensitive routes; custom-model URL + key-env validation (local endpoints still allowed); exact-value secret scrubbing; delivery-queue no longer drops a concurrently-enqueued message; colliding cron name-slugs get distinct wrappers; Agent SDK API-key save fixed; trend-tick liveness recorded up-front; fresh-restart-not-a-crash; tidied internal inconsistencies. No capability removed. |
| **v5.51** *(June 2026)* | Codebase hardening (security + reliability) | A whole-codebase audit fixed a batch of real issues: safer web-fetch (no command-smuggling via URLs + network-destination guard incl. IPv4-mapped IPv6), symlink-proof file-write guard, a background-task counter leak that slowed responses, `/stopall` now stops detached tasks, auto-follow-ups run on the default backend, provider health watches the runtime-switched provider, and config-write fixes (`$` values, wrapped cron jobs, no duplicate keys). |
| **v5.50** *(June 2026)* | Setup glow-up + newest-first models | The `alvin-bot setup` wizard got a visual + UX pass: aligned banner, progress rail, color (graceful when off/piped), Agent-SDK-first provider list with `free`/`paid`/`premium`/`offline` chips and real descriptions (previously blank placeholders). The model picker is newest-first with friendly names and ★/🆕/💎/⚡ badges; Enter takes the recommendation, one key expands the full live list. The same ranked display powers the web dashboard. "Newest" now correctly ranks a higher version above an older dated build. |
| **v5.49** *(June 2026)* | Guardian hierarchy — network ≠ crash | The two failure guards (in-process reconnect loop, hard watchdog restart) shared one 90s threshold, so every Wi-Fi blip became a counted "crash" that later fed scary-but-wrong trend alerts. Now the reconnect loop heals first and retries through any outage; the watchdog only restarts on a true freeze (both guards silent). Offline boots wait instead of crash-looping, health metrics exclude their own diagnostic noise, trend warnings dedupe structurally (one per problem + 3-day reminder), and restart notices carry the recorded cause. |
| **v5.45 – v5.48** *(June 2026)* | Background-task honesty + scheduler self-heal | Dead detached tasks reported in seconds with real per-task health and cancel support; shell jobs can't freeze the bot; the scheduler heals itself; token-free provider health checks; `@daily` shorthand; `/verbosity` everywhere; owner opt-outs. |
| **v5.44.1** *(June 2026)* | Sleep-aware crash-backstop | The external crash-backstop that restarts a frozen bot is now sleep-aware too (the in-app watchdog already was, since v5.33): it clamps the staleness window by how long the machine has actually been awake, so a laptop that merely slept past the threshold no longer triggers a spurious restart on wake. A genuine freeze on an awake machine is still recovered. Self-applies on next start; always-on desktops were never affected. |
| **v5.36** *(June 2026)* | No reconnect spam on wake | A laptop wake re-establishes the dropped Telegram connection silently instead of DMing a "subsystem restart" every time — recognised by the sleep-sized staleness / recent resume. A genuine runner failure still notifies. Completes the sleep-hardening series. |
| **v5.35** *(June 2026)* | Reliable update + sleep-calm | `/update` fixed for `npm install -g` (skips the flaky Puppeteer Chromium download) and survives a dropped network mid-update; watchdog grants a post-wake reconnect grace window; trend monitor no longer flags a frequently-sleeping laptop's reconnect noise as a crash loop. |
| **v5.34** *(May 2026)* | Budget cap off by default | The optional `MAX_BUDGET_USD` daily cap no longer blocks anyone unless explicitly opted in (`BUDGET_ENFORCE=1`). Fixes a surprise "$X spent today" wall users hit after updating (the shipped example config had set a $5 cap that used to be ignored). |
| **v5.33** *(May 2026)* | Laptop-sleep resilience | The health watchdog now detects a resume-from-suspend (large wall-clock jump between checks) and re-arms instead of restarting — no more sleep-induced restart loops or false "crash" alerts on laptops. A genuine hang is still caught on the next check. |
| **v5.32** *(May 2026)* | Maintainability split | Largest source files broken into smaller modules (command groups; the web dashboard's 3,300-line script → core/panels/views) with byte-verified identical behavior. |
| **v5.31** *(May 2026)* | Defense-in-depth | File-write tools refuse credential/persistence/system paths (`.env`, `~/.ssh`, `LaunchAgents`, `/etc`); external MCP servers get a secret-free environment (no bot token / API keys); web, search, and MCP output is fenced as untrusted "data, not instructions" with injection heuristics; documented threat model in `SECURITY.md`. |
| **v5.30** *(May 2026)* | Maintainability + watch mode | `npm run dev:watch` / `build:watch` for source development; the largest command file split into per-area modules (cron, sub-agents) with no behaviour change. |
| **v5.29** *(May 2026)* | Sub-agent visibility | `/subagents list` marks detached agents that will auto-continue when they finish with a ↪️. |
| **v5.27 – v5.28** *(May 2026)* | Security + stability hardening | Web UI requires a password on **every** channel (incl. the live chat socket) when exposed; pattern-based destructive-command guard for the shell tool; plain-HTTP exposure warning; opt-in `MAX_BUDGET_USD` daily cap actually enforced; clear startup messages for common misconfigs; dropped external MCP tool-servers auto-reconnect with backoff. |
| **v5.25 – v5.26** *(May 2026)* | Dashboard + auto-continuation | `/status` rebuilt as a clean, human-readable dashboard with provider-aware limits and reasoning mode; a finished background task can auto-run a promised follow-up, toggled per chat with `/continuation`. |
| **v5.24.7** *(May 2026)* | Thinking-loop self-heal | An extended-thinking API error that could survive a `/restart` (poisoned session anchor) now auto-resets the SDK session on detection — conversation history preserved, no `/new` needed. |
| **v5.24.6** *(May 2026)* | Restart hotfix | v5.24.5's explicit self-relaunch is now a **fallback**: the bot waits a grace window for the OS service manager to respawn it on its own, and only relaunches itself if it doesn't. Fixes the double-spawn (service-manager respawn + explicit relaunch) that briefly ran two instances → Telegram 409 → `/restart` reconnect loop on healthy setups. All self-preservation layers unchanged. |
| **v5.24.5** *(May 2026)* | Self-relaunching restart | Self-restarts now schedule their own relaunch after a clean exit instead of waiting on the OS service manager, whose automatic respawn can stall on long-uptime sessions and leave the bot down after a `/restart` or `/update`. The optional crash-backstop watcher also self-installs on boot if missing (covers setups that only ever updated in place). |
| **v5.24.4** *(May 2026)* | launchd-safe restart | `/restart` + `/update` route through `scheduleGracefulRestart()` for an orderly teardown (Telegram offset commit + long-poll close, port 3100 release, WhatsApp socket close) instead of a bare PM2-era `process.exit(0)` that left lingering resources blocking the launchd respawn on WhatsApp-enabled installs. restart-storm.json test-pollution closed at the source (lazy path + test isolation). |
| **v5.24.3** *(May 2026)* | Quieter logs | Trends-AI debounce (4 h signature cache) — restart-storms no longer fire one redundant AI call per restart with identical to-be-suppressed verdict. Ollama preload silent when the daemon isn't running — public users without Ollama don't see a "[ollama] preload warning" red flag on every boot. |
| **v5.24.2** *(May 2026)* | Files born private | `delivery-queue.json`, `cron-jobs.json`, and `memory/YYYY-MM-DD.md` daily logs now write with `mode: 0o600` explicitly so the startup file-permissions audit no longer needs to repair them on every boot. The recurring `🔒 file-permissions: repaired N` log line stops appearing in normal operation. |
| **v5.24.1** *(May 2026)* | Test-pollution sentinel | Vitest `globalSetup` snapshots production state files before any test file loads, re-checks SHA-256 after the suite — `npm test` now fails non-zero on any future test that writes into the user's real `~/.alvin-bot/`. Closes the regression vector that v5.24.0 mitigated only for the two known polluters. |
| **v5.24** *(May 2026)* | Beast Mode | `lastSdkHistoryIndex` reindexed after every compaction (latent bridge-anchor bug closed). SDK-path compaction enabled — the local history shadow no longer balloons and long SDK sessions feed the memory pipeline. Trend-WARN noise floor raised: malformed AI responses no longer become `(no description)` alarms, suggestions are platform-aware (`journalctl` only on systemd-linux), stale installs get an explicit `/update first` hint. Sanitizer-residue gate widened 0.25 → 0.5 kept-ratio so the canonical 38 %-kept incident shape is actually caught. Bonus: three test files no longer pollute production state. |
| **v5.23** *(May 2026)* | No-more-hangs, never-lose-the-thread | Stalled-output guard for the async-agent watcher: a sub-agent that silently dies mid-run (OOM, parent-restart orphan, re-fork that strands the parent pid) is declared failed after 5 min of no output-file writes — releases `pendingBackgroundCount` and frees the bot from bypass-bridge mode. Pre-bypass compaction: the bridge inject ships a stable narrative summary + last 10 turns instead of every raw turn, so the prompt is small and the provider's prompt cache hits across consecutive bypass-turns (TTFT 5-15 s → sub-second on turn 2+). Sanitizer-residue guard against role-confused history: a leaked `<system-reminder>` block collapsed to a tiny quote-fragment no longer lands as `role: assistant`. |
| **v5.22** *(May 2026)* | Hardcore foundation — dedup + ambient memory + privacy | Sub-agent doppel-spawn-guard (60s window, prompt-hash dedup); `/cancel` + `/stopall` cover detached subprocesses too with PID-command-shape verification; ambient memory search on EVERY turn (not just first SDK turn) — the USP fix; privacy-check.sh now scans git-tracked source in addition to tarball; internal planning docs removed from git tracking. |
| **v5.21** *(May 2026)* | Context-continuity restored | Bypass-bridge no longer caps at 10 turns (was the main USP-breaker mid-conversation); bridge size cap raised 2.5 k → 32 k so a 30-turn detailed session survives intact; background-agent results carry a structural `[BACKGROUND-AGENT RESULT — async side-channel]` marker so parallel agents can't hijack the conversation thread; standing rule in the project rules file to check memory/history before asking the user to repeat. |
| **v5.20** *(May 2026)* | Sub-agent results integrate into history | Telegram reply-quotes on background-agent results now keep context — the result is written to the parent session's history at delivery time (inline / multi-chunk / file tiers all handled), capped at 4 kB per entry. Eliminates the "generic A/B/C answer after reply-quote" pattern. |
| **v5.19** *(May 2026)* | Reliability surface | New `Reliability` tab in the WebUI: restart-storm counter, state-file health, recent incidents, `EXEC_SECURITY` mode, live TTS-provider switch. Subsystem restarts (telegram-poll in-process) DM the owner instead of being silent. State-quarantine findings DM after boot. Incident dumps auto-prune after 30 days. |
| **v5.18** *(May 2026)* | Reliability foundation | Cron auto-fix (silent allowlist + auto-wrap for piped commands) restores the "create job, it runs" feel; `launchctl` / `pkill` / direct-kill-our-pid routed through graceful restart instead of OS SIGKILL; restart-storm-brake refuses the 4th self-restart in 10 min; post-restart "🦊 Wieder da" ping after every non-cold-boot; state-file health check at boot quarantines corrupted `sessions.json` / `cron-jobs.json` / `delivery-queue.json`; new `EXEC_SECURITY=full` Power-Mode opt-in in `alvin-bot setup`. |
| **v5.17** *(May 2026)* | Scaffolding-echo hardening + local TTS default | Four independent sanitizer layers (stream / handler / history-write / bridge) block a class of confused-model failure where the underlying LLM emitted `<system-reminder>` scaffolding as if it were a reply; the bot used to DM it verbatim AND re-inject it via the bridge, self-reinforcing. Plus Supertonic local TTS is now the default for fresh installs (lazy auto-install on update), Unicode-safe text path, `/tts <provider>` to switch live. |
| **v5.15 – v5.16** *(May 2026)* | Update + observability hygiene | `/update` survives the `NODE_ENV=production` devDeps trap and stays bilingual; outbound log scrubber now exempts the owner so you can still see your own `.env` contents in DM; cross-platform CI matrix runs on an injected clock so a stable test suite no longer depends on the runner's timezone. |
| **v5.14** *(May 2026)* | Concurrent updates → `/btw` live steering works | Updates are now processed concurrently via the grammy runner (normal messages still serialized per chat), so a `/btw` note — or a mid-task `/stop` — is received and applied *while* a task streams, instead of queuing behind it. Live steering uses the Agent SDK provider. |
| **v5.13** *(May 2026)* | Prompted-tool sub-agents (opt-in) | `SUBAGENT_PROMPTED_TOOLS=1` lets models without native function-calling run background sub-agents via a strict prompted protocol — capped, honest best-effort degradation, same exec guardrails. Off by default (zero change unless enabled). Completes provider-agnostic background sub-agents. |
| **v5.12** *(May 2026)* | Background sub-agents beyond the Agent SDK | Function-calling providers (Groq, OpenRouter, NVIDIA NIM, Gemini, capable Ollama) now run background sub-agents via a detached worker reusing the same tool layer + exec guardrails + delivery/reconciliation. Agent SDK path byte-for-byte unchanged; non-function-calling models keep the graceful fallback. |
| **v5.11** *(May 2026)* | Provider-agnostic sub-agent groundwork | Internal dispatch backend seam; on installs without the agent CLI a background-task request now returns an honest message via the normal result path instead of erroring. Agent SDK path byte-for-byte unchanged. Follow-ups add a generic worker for the other providers. |
| **v5.10** *(May 2026)* | Answer-detail control + real `/btw` | `/verbosity short\|medium\|full` (medium = unchanged default) applied uniformly across all providers; `/btw` is now an actual discoverable command on every messenger — steers a live Agent SDK task or replies honestly instead of the old silent no-op. |
| **v5.9** *(May 2026)* | Quieter, honest health alerts + fixes | Trend monitor no longer false-alarms after an update (ignores version-change churn, requires a real recurring fault, 24 h debounce); macOS sudo/keychain setup fixed (was hanging with "exit null"); 7-day screenshot auto-cleanup now covers the CLI temp dir + on-demand `/cleanup`. |
| **v5.7 – v5.8** *(May 2026)* | Distribution hardening | Leaner, more tamper-resistant published package; local dev stays fully readable. Verified by fresh global install on a clean machine. |
| **v5.3 – v5.6** *(May 2026)* | Control + delivery UX | Live `btw …` steering of a running task, honest instant ⛔ Stop with confirmation, compact background-task delivery (tight header + answer, long output as one file), 48 h monitor self-heal. |
| **v5.0 – v5.2** *(May 2026)* | Reliable mid-task stop + hardening | Dependable `/cancel` (soft) and `/stopall` (hard) with an inline ⛔ button; whole-project security + bug-hardening pass. |
| **v4.22** *(May 2026)* | Memory architecture overhaul | Pluggable embedding providers — **Gemini · OpenAI · Ollama · FTS5 (zero-config keyword fallback)**. Auto-detection picks the best available, so users with no API key still get a working indexed memory store. Smart inject mode stops bulk-injecting `MEMORY.md` once SQLite is populated. |
| **v4.21** | Agent Browser skill | Tier-1.5 token-efficient web automation via the [agent-browser](https://github.com/vercel-labs/agent-browser) CLI — opt-in by install. ~90 % token reduction vs Playwright on cooperative pages. |
| **v4.20** | SQLite-backed vector memory | Replaces the legacy 128 MB JSON index. Automatic migration on first start, per-chunk INSERT/UPDATE, lazy native binary load with graceful fallback. |
| **v4.18 – v4.19** | Reliability + per-workspace overrides | SDK auto-recovery on token rotation / quota exhaustion / empty streams. Per-workspace `effort` / `provider` / `voice` / `temperature` / `toolset`. |
| **v4.17** | Hardening audit | Disk cleanup service, hardening fixes from internal audit. |
| **v4.13 – v4.14** | Detached sub-agents | `alvin_dispatch_agent` MCP tool spawns independent CLI subprocesses that survive parent aborts. Multi-platform dispatch (Slack / Discord / WhatsApp). Watcher zombie guard. |
| **v4.10 – v4.12** | Multi-session + Slack | Workspace registry with hot-reload, per-channel personas + cwd, Slack adapter with progress ticker + typing status, owner approval gate, async sub-agents. |

### 🏛️ 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

| Priority | Item | Why |
|---|---|---|
| **P0** | MCP plugin sandboxing | MCP servers currently run with full Node privileges. Plan: child process with restricted FS + network policy (deno-permission style). Architectural change. |
| **P1** | Electron major upgrade (35 → 41+) + Windows `.exe` | Closes desktop-build CVEs, unblocks the only platform still missing a native installer. |
| **P1** | Prompt injection defense policy | Needs a design decision (heuristic filter / allow-list / accept-the-risk with clearer warnings) and consistent enforcement at every message entry point. |
| **P2** | Per-workspace memory layer | Partially shipped in v5.65 (workspace-shared lane recall, opt-in). Remaining: scope facts learned in the MAIN conversation per workspace unless explicitly promoted. Builds on the v4.22 SQLite store. |
| **P2** | Per-workspace skill allowlist | Scope Apple Notes to personal workspace, sysadmin tools to devops only, etc. |
| **P2** | Multi-user Slack (`per-channel-peer`) | Different users in the same Slack channel get their own sub-sessions. |
| **P2** | Live steering (`/btw`) for file, photo & document tasks | Attachments run on a handler path that never opens a steer channel, so `/btw` can't nudge them mid-task yet (it replies honestly instead). Plan: extend the streaming steer setup to the attachment handlers. |
| **P3** | Linux `.AppImage` / `.deb`, Homebrew formula, Scoop manifest, one-line install script | Platform reach for non-npm users. |
| **P3** | Workspace cloning / templates | `/workspace clone my-project as my-fork` spins up a new workspace from an existing one. |
| **P3** | TypeScript 5 → 6 | 5.x still supported; strict-mode break-fix work, not urgent. |

Pull requests welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).

---

## 🔒 Security

> ### ⚠️ Important: Alvin has full shell + filesystem access
>
> Alvin Bot is an **autonomous AI agent** built on an 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 a coding agent 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`](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.
- **`ALVIN_FREIE_HAND=1`** (v5.139.0, off by default) — lifts **every** tool guard for owners who want their bot unrestricted: the command guard, the write-path guard including system directories, and the shell allowlist. Responsibility moves to you; the bot says so at startup and in `/status`. Who may use the bot (`ALLOWED_USERS`, pairing) and the fencing of external content are unaffected.
- **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.

---

## 📄 Licence, attributions and your responsibility

Type **`/about`** in the bot for the short version at any time. It is also shown
before the setup wizard writes anything, where you can decline.

**Alvin Bot is proprietary.** See [LICENSE](LICENSE). It is licensed, not sold:
you may install and run it on machines you control, including commercially.
Redistribution and resale are not permitted. It is **not** open source.

**Use is at your own risk.** This software acts on your behalf — it runs shell
commands, reads and writes files, browses the web, sends messages on the
channels you connect and, where you switch it on, keeps working unattended. You
decide what it may do, with which credentials and for how long, and you remain
responsible for what happens under your accounts, for any cost it causes, and
for the consequences of its actions. Model output can be wrong; verify anything
that matters.

**Not everything it builds on is open source.** The agent SDK and the CLI
binary it runs are proprietary software of their vendor, and their use is
governed by that vendor's own agreements between **you** and the vendor. The
vendor and the link to those terms are named in
[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md). Alvin Bot runs the binary
unmodified, you authenticate with your own credentials through the vendor's
own flow, and no credentials or usage are collected, stored, resold or
intermediated. Alvin Bot is not built, endorsed or sponsored by that vendor or
by any provider or platform named in this document, and no affiliation is
claimed.

The same holds for every model provider and messaging platform: you bring your
own keys, their terms apply to you directly, and their names are used
descriptively only.

Full attributions — including the two copyleft dependencies, named individually
— are in **[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)**, which ships
inside the package. Dependencies themselves are not redistributed: your own
package manager fetches them under their own licences.

---

## 🤝 Feedback

Bug reports and feature requests: alvbln7@gmail.com
