astrbot_plugin_proactive_chat: making an AstrBot instance speak first

The gap this plugin was written to fill

Most chat bots are reactive. They answer when spoken to and stay silent otherwise, which is exactly the behaviour that makes a companion-style deployment feel like a command line rather than a presence. The author states the motivation directly in the README: after browsing the AstrBot plugin market, he found plugins for proactive replies but none he considered a usable proactive message plugin, and decided to fill that gap. The distinction matters. A proactive reply still waits for a trigger; a proactive message originates from the bot after a session goes quiet. The intended audience is narrow and clearly stated: people who want emotional companionship from an AI, or who want their bot to read as more human. It is not a notification scheduler for ops alerts. The trigger is user silence, not a cron expression, and the message is generated with persona and context rather than templated.

How a silent session turns into an outgoing message

The mechanism described in the README is a silence timer. When a given conversation has had no new messages for a configured period, the plugin schedules a proactive message at a random point inside a configured time range. That randomization is deliberate: a bot that always speaks at exactly the same offset reads as a scheduler, not a person. Each conversation carries its own state, counters and triggers, and the README describes sessions as fully isolated so that activity in one private chat cannot disturb the timer in another. The plugin supports many private and group sessions at once, each with its own configuration and an optional note name. On reload, the README states the plugin can start creating proactive message tasks automatically, without a user input to activate it. The single most important design fact is stated plainly in the README: nearly every plugin that implements proactive messaging does so by emitting a simulated user message, and this one follows that approach. The model is not being asked to volunteer; it is being handed a fabricated turn and asked to respond to it. That is why the README ties output quality to prompt quality, persona and model capability rather than to any scheduling parameter.

Context, emotion and the do-not-disturb window

Three features sit on top of the timer. Context awareness lets you choose where the bot looks when composing a message, so it can review history rather than firing blind after a long silence. Dynamic emotion means the generated message carries a state rather than a fixed tone, which is what keeps consecutive proactive messages from reading identically. Do-not-disturb periods suppress the trigger during chosen hours, which is the difference between a companion and a nuisance at 03:00. TTS integration is listed as a feature, and the README also publishes a platform adaptation table, which suggests TTS support is not uniform across adapters. The README's own framing is worth repeating: the plugin provides the scheduling, the state and the plumbing, and the prompt provides the personality. If the proactive messages feel flat, the README points at the prompt, the persona, the model and the richness of the supplied context, not at the trigger logic.

Installation and the configuration surface

The README states the plugin targets AstrBot v4.8.0 or newer, is marked compatible with AstrBot v4.27.4, and requires Python 3.10+. The repository layout and the badge set indicate the plugin is installed into an AstrBot instance as a plugin, and that the plugin exposes a configuration section with per-session entries: silence threshold, the random trigger range, context source selection, do-not-disturb hours, and a note name for each session. The README carries a dedicated section for the individual configuration keys, and that section is where the exact key names live. I have not installed or run this project, so I cannot reproduce the key names or a working install command from the material I have; the README's configuration section is the place to read them, and the plugin market is the documented distribution path. What the material does establish is the shape of the setup: you enable the plugin, then configure each conversation you want covered, because sessions are isolated and nothing is global by accident.

The WebUI is a separate application, not a settings page

The plugin ships an independent WebUI for personalized configuration, and the topics list on the repository names React, JavaScript, JSX, CSS and Material UI. That is a full front-end stack, not a form rendered by AstrBot. The practical consequence is that the WebUI is a second moving part: it can be configured through a browser, and it also has to be built or served, which is a different maintenance burden from a plugin whose only surface is the host's config file. The README describes it as a modern console and treats it as a headline feature, and for multi-session setups that is reasonable, because editing per-session triggers, quiet hours and context sources as raw config grows unpleasant quickly. The trade-off is honest: you get a real interface, and you inherit a front-end dependency alongside the Python plugin. Whether the WebUI is bundled in a release or built from source is something to confirm against the release you pull, because the material I have does not say.

Where this design breaks down

The failure mode is named by the author himself. Because the proactive message is a simulated user message, the model can break character: it may answer the fabricated turn in a way that reveals the trick, or produce something that reads as a system nudge rather than a person starting a conversation. Prompt tuning is not optional polish here, it is the load-bearing part of the output quality. The second limitation is timing. The trigger fires inside a random range, so you cannot promise a message at a specific minute; if your use case needs deterministic delivery, a plain scheduler is the correct tool and this plugin is the wrong one. Third, the project is young and self-described as in a relatively stable development stage, with a known-limitations section in the README that should be read before deployment rather than after. Fourth, the author is explicit that all files were written by AI under his architecture direction, with the README carrying a warning that the plugin and documentation are AI generated and should be checked carefully. That is transparency, and it is also a reason to read the code paths that matter to you rather than trusting the feature list.

What to compare it against

The README names two projects as the author's reference points: KouriChat and LingChat. The difference in approach is architectural. KouriChat and LingChat are standalone companion applications: you deploy them, and the companion behaviour is the product. This plugin is a plugin, so it runs inside an AstrBot instance you already operate. The author states the motivation for that choice outright, that running one AstrBot instead of an additional multi-threaded service matters on a small cloud server. The trade is real in both directions. A standalone companion app can own its memory, its scheduling and its interface end to end, while a plugin inherits the host's adapter support, its update cadence and its plugin API. If your bot already lives in AstrBot and you want proactive messages without a second deployment, the plugin is the smaller footprint. If you want a companion that is the whole application, the standalone projects are the closer match, and the README treats them as such.

Licence and the cost of staying current

The repository is AGPL-3.0. If you run a modified version as a network service that others interact with, that licence family carries source-availability obligations, and this is the point at which you should read the licence text and, if the deployment is commercial, ask someone qualified. I am not giving legal advice here. On maintenance: the release history shows v1.2.3 in May 2026, v1.2.4 at the end of May 2026 and v1.2.5 at the end of August 2026, with the last push to main in early September 2026. The README states the author will keep maintaining the repository and the plugin. The practical upgrade cost is concentrated in two places. The plugin is built against a newer AstrBot and the README recommends the latest AstrBot for the best experience, so an AstrBot upgrade can require a plugin update. And the WebUI is a React application, so a change to the interface means touching a front-end build in addition to the Python side. Budget for both when you plan upgrades, and check the release notes for the version you intend to run.

Editorial conclusion

Adopt it if you already run AstrBot v4.8.0 or newer, want private and group sessions to receive unprompted messages after silence, and are willing to tune the proactive prompt and persona yourself, because the README states the plugin works by sending a simulated user message and that a good prompt is what keeps the model in character. Do not adopt it if you need guaranteed timing (the interval is randomized), if you cannot accept AGPL-3.0 terms, or if a TTS path is a hard requirement without checking the platform table first. Before installing, verify three things: your AstrBot version against the v4.8.0 floor and the v4.27.4 compatibility badge, whether the OneBot 11 adapter you use appears in the platform adaptation table, and whether the WebUI ships in the release you pull or has to be built from the React sources.

Official sources

1. Issues
2. License: AGPL-3.0
3. Pancakes-Labs/astrbot_plugin_proactive_chat on GitHub
4. README
5. Releases