Technology ·
I Built a QQ Notification Skill So I Could Stop Watching My Agents
This is a text edition. Images, polls and embedded content from the original are not yet included; see the original source below.
OPEN SOURCE · AGENT HOOK I Was Tired of Watching My Agents, So I Made a QQ Notification Skill Task complete, waiting for you, or approval needed—your phone will alert you.
I Was Tired of Watching My Agents, So I Made a QQ Notification Skill
Lately I have grown used to opening several agent conversations at once: one researches, one edits code, another handles deployment, and yet another organizes documents.
That created a problem.
I cannot stare at every window all the time. Sometimes I switch to something else and forget which conversation has ended; sometimes I pick up my phone and remember half an hour later that the task finished long ago. At other times an agent is stuck at an approval dialog while I think it is still working.
Agents can already work on their own, but someone needs to tell me when they finish.
The occasional glance back seems like a small action, but together those glances keep breaking my concentration. I start wondering: Has it finished? Did it fail? Is it waiting for me? I delegated the work to an agent to reduce waiting, only to end up polling windows in a less obvious way.
So I built qqbot-task-notify: an open-source skill based on the official QQ Open Platform Bot API. It listens for key coding-agent events and proactively sends a brief alert to my QQ account.
LOCK SCREEN · REAL NOTIFICATION
Now, even with my screen locked, I know which conversation has finished.
01 · WHY What I wanted was not a remote control but a 'finished-work bell.'
Many providers now let you control agents through WeChat, Feishu, and other apps. But with the two products I was using then, getting the result of a turn on WeChat usually meant starting that turn from WeChat.
That is not quite how I work. I still start most tasks on my computer, where the project files, terminal environment, and context live. I do not want to move the whole workflow into a chat app. I just want my phone to tell me, after I leave the computer, that it has finished or is stuck waiting for me.
I also tried related WeChat bot solutions, but concerns about interaction windows and risk controls made me unwilling to rely on them for the whole notification chain. By comparison, the official QQ Open Platform Bot is more open and lets me connect multiple agents and conversations to a single notification endpoint.
THE DIFFERENCE Remote-control bot: start a task in a chat app and receive the result there. This skill: start the task anywhere and get called back only at key points.
It does not try to take over the agent, reply to approvals for you, or reproduce the entire coding interface in QQ. It intentionally only sends notifications, so it can work independently of where a conversation began. I can start a task from the desktop today and from a terminal tomorrow; the notification logic remains the same.
02 · NOTIFICATIONS Three kinds of message are worth interrupting me for now.
Not every agent event deserves a phone notification. If every tool call made the phone ring, notifications would become a new source of noise. I kept only three points where a human really needs to re-engage:
Task complete: a turn ends and the message contains the agent name and conversation title. I no longer have to check every window or leave a completed result sitting in the background for half an hour. Waiting for you: I am alerted as soon as the agent asks a question, submits a plan for approval, or needs me to choose. It no longer appears to be running while actually stopped at an interaction point. Permission request: I am alerted when a tool call or elevated permission needs approval. A human still confirms sensitive operations; the notification merely shortens the wait.
Completion and waiting alerts from different times and conversations all arrive in QQ.
In practice, this changed not the speed of an individual task but how I arrange tasks. I used to open only one or two conversations, because with more I lost track of who was doing what. Now I can assign research, code changes, and document work separately, then go eat, attend class, or handle other things.
QQ tells me by conversation title which task finished first, which needs a choice, and which awaits permission. Alerts do not send the whole conversation, just the minimum information needed to identify the task. My attention is no longer repeatedly cut up by the question, 'Has it finished yet?'
An ordinary afternoon using it 14:00 I ask one conversation to analyze a repository, another to edit a page, and a third to run tests. 14:08 My phone says 'Waiting for you': the page edit needs me to choose between two approaches. 14:16 The test conversation finishes first; I return to the computer to inspect the result while the repository analysis continues in the background. 14:27 The final completion alert arrives. I check all three results together instead of opening three windows in rotation for more than twenty minutes.
That is also why I did not turn it into a live task-progress feed. Usually I do not need to know what tool the agent just called or which file it is reading; those details belong in the original conversation. A phone notification needs to answer only two questions: Do I need to act now, and which conversation should I return to?
03 · HOW IT WORKS It does just one thing but makes the whole chain work
The Agent triggers a key event ↓ A Hook captures it and extracts a short session title Send directly from the local machine / keep a local process running / relay through Linux ↓ QQ Open Platform's official C2C API A notification arrives on your phone
The repository offers three deployment options; you do not need to buy a server just for a notification tool:
A · Send directly from your machine | Recommended for getting started Works on Windows / macOS. A single file using only Python's standard library calls the official API directly, without a server or resident process. Suitable for getting completion notifications working first. B · Keep a local process running | Stay connected Maintain the Bot gateway connection on your own computer; you can complete one-time pairing and maintain online status, still without a public server. C · Linux relay | Share across multiple machines For people who already have a server or use several computers or Agents. Keep AppSecret centrally on the server and share one notification outlet across devices.
The Hook does not write notification results back into the normal answer. Even if the network temporarily goes down, the QQ API fails, or the server is unreachable, the script exits quietly and writes only one redacted local log entry. In other words, if the notification chain breaks, the Agent should still finish its task normally.
This principle matters for automation tools. Notifications are an extra capability, not a new dependency of the main task: temporary QQ unavailability must not cause code generation to fail; failure to read a title must not block a response; and trying to 'guarantee delivery' must not produce endless retries that spam the same message dozens of times. The Hook in the repository therefore always returns success; failures are left only for local troubleshooting.
What exactly gets sent in a notification? A completion notification usually contains only the Agent's name and a truncated session title; a waiting notification adds an event type such as 'question, plan approval, or permission request.' By default, it does not push the last response, the full prompt, code content, or tool results to QQ. The notification's job is to point you to the session, not copy it.
The repository currently includes integration templates for ZCode, Claude Code, Codex, and WorkBuddy. Session titles are extracted first from the structured information each provides; if unavailable, they fall back to fixed wording rather than reading or sending an entire conversation just to obtain a title.
ZCode Completion + questions + plan approval + permission requests Claude Code Completion + waiting notifications Codex / WorkBuddy Currently support completion notifications; waiting events are limited by upstream capabilities (you can let your Agent upgrade this on its own).
I deliberately did not describe the four platforms as having 'exactly the same capabilities.' What notifications can do depends first on whether the Agent itself exposes the corresponding events. Codex currently has only a callback at the end of a full turn, so it can reliably provide only completion notifications; waiting notifications can be added when upstream exposes pause events in the future.
04 · SECURITY Why I chose an official QQ Bot
This project uses QQ Open Platform's official API, not a personal QQ protocol, reverse-engineered login, or a simulated OneBot solution. You need to create your own bot on QQ Open Platform and comply with its terms of service and proactive-message policy.
'Being able to send a message to QQ' is only the outermost layer. The real pitfalls are: who may bind the bot, where credentials are stored, whether the notification API is exposed to the public internet, and whether logs record whole conversations and tokens. The repository therefore writes the following boundaries into its default templates:
Only a QQ account that sends the correct one-time pairing code can be bound as owner; the first person to send a message is not automatically treated as the owner; After a pairing code is used, a consumption marker remains, so an old binding message cannot simply be replayed even if the state file is lost; Credentials live only in a private local file or a root-only environment file on the server, never in the repository or examples; By default, the server notification endpoint listens only on 127.0.0.1; a public port is not opened just for notifications; Logs do not record notification bodies or output Secrets, access tokens, or full openids; Notification failures must never block an Agent response, nor trigger automatic retries that flood the recipient.
One boundary worth explaining QQ proactive messages may still be subject to the platform's frequency and interaction-window policies. If sending fails after a long period without interaction (about one month), send the bot a message to reestablish the interaction window. This is not a way around platform policy; the exact entitlements always depend on the QQ Open Platform console at the time.
05 · GET STARTED No need to read all the documentation: send this paragraph to your Agent
Complete integration means creating an official QQ Bot, choosing a deployment option, pairing the owner, registering the Agent Hook, and verifying with a real event. There are several steps, but most are well suited to having the Agent work through the repository documentation one by one.
The easiest way is to send the following prompt verbatim to the Agent you are using:
COPY THIS PROMPT Help me clone the https://github.com/KerryChia/qqbot-task-notify repository and guide me through choosing a setup, creating an official QQ Bot, and configuring the notification chain. Recommend the serverless local direct-send option first; when credentials are needed, only guide me to put them in private configuration. Do not echo sensitive information such as AppSecret, tokens, or openids in chat, logs, or the command line. After setup, use a real Agent event to verify a task-completion notification.
During integration, complete at least these four checks 01 Send a test message manually and confirm QQ receives it 02 Complete a real Agent conversation and confirm automatic triggering 03 Trigger a question or approval point and check the waiting notification 04 Temporarily disconnect the network and confirm notification failure does not affect the answer
If you already have a Linux server, you can have it choose the server-relay option; if you just want to try it, start with local direct-send. Do not mistake the presence of systemd, gateway protocols, and security templates in the repository for a requirement to complete an entire server deployment first.
It is especially suited to these people People running multiple coding sessions at once who do not want to track progress from memory; People who frequently leave long tasks running in the background while they step away from the computer; People who still start tasks on the computer but want their phones to receive only key milestone notifications. If you always have only one short session open and sit at the computer throughout, the benefit may be limited. What this tool really solves is the information gap caused by multitasking, long waits, and stepping away from the screen.
Three things you can do after reading 01 Open the GitHub repository and Star it for later 02 Copy the prompt above and let your Agent help you integrate it 03 Open several sessions at once, then step away from the computer with peace of mind