pi-overwatch-progress-telegram

An independently implemented Pi sidecar that summarizes ongoing task progress with a separate AI model and sends Telegram notifications. It does not inject messages into the foreground model or Pi HUD.

Install

# From this repository's root:
pi install .
# Or install a published npm version that includes the completion check.
pi

Run commands inside Pi's interactive input, not in your shell. Restart Pi (or reload extensions) after installing a new version. Run pi list to verify the installed version; remove any standalone ~/.pi/agent/extensions/pi-overwatch.ts to avoid two observers.

Configure

• /pi-overwatch-login — prompts for a numeric Telegram Chat ID and a Bot Token. The token is visible while typing, as requested, but is never shown in /pi-overwatch-config status. Do not put credentials in a slash command's arguments or a normal chat message.
• /pi-overwatch-model — prompts for provider/model-id, or use /pi-overwatch-model provider/model-id. The model must be available in Pi; authenticate with Pi separately. Unsupported saved thinking levels reset to off when you switch models.
• /pi-overwatch-thinking — choose an independent sidecar thinking level from a popup; or pass off|minimal|low|medium|high|xhigh|max. Unsupported levels are rejected. Default: off. Pi's foreground thinking setting does not affect this observer.
• /pi-overwatch-threshold — enter a weighted activity threshold between 1 and 100 (up to two decimals); or supply it as an argument, e.g. /pi-overwatch-threshold 12. Default: 8. This changes the threshold, not the 6–12-minute timing window.
• /pi-overwatch-config on — enable the observer from this point forward, discarding all older activity. Running on again begins a fresh window.
• /pi-overwatch-config off — stop the observer, pending progress and finish alerts immediately; the choice persists.
• /pi-overwatch-config status — show enabled state, model, thinking, threshold, interval, and Telegram configuration without revealing the token.
• /pi-overwatch — show the last progress report in this conversation.

Older aliases continue to work: /pi-overwatch-config telegram|id|token|model|thinking|threshold. An empty /pi-overwatch-config prints the command list. Commands that need a value without one open an interactive prompt; canceling or leaving it blank reports that nothing was saved. All configuration prompts and notifications are in English.

Model, thinking, threshold, and on/off are stored under piOverwatch in ~/.pi/agent/settings.json. Telegram credentials are stored unencrypted in ~/.pi/agent/pi-overwatch/telegram.json (created with owner-only permissions where supported); protect your OS account, terminal screen, and backups. The credentials file is not bundled or removed by log cleanup. PI_OVERWATCH_TG_BOT_TOKEN and PI_OVERWATCH_TG_CHAT_ID remain fallbacks for missing saved values. PI_OVERWATCH_MODEL="provider/model-id" remains a fallback for model choice (legacy provider:model-id is accepted). Monitoring defaults to off unless piOverwatch.enabled was explicitly saved as true. Starting, reloading, or resuming Pi starts a new observation window at the current end of the conversation, never a backfill.

Notification behavior

• Each monitoring cycle begins with the first new activity after enabling, or after the previous progress alert. Progress alerts are never sent before 6 minutes. At 6 minutes or later, reaching the configured activity weight sends one summary. At 12 minutes, any pending activity sends a summary even below the threshold. An idle period without new activity sends nothing.
• Pi's agent_settled event means the run stopped, not that the user's task is finished. On an un-aborted run, the observer checks for a final assistant reply, no queued messages, and calls the sidecar model once more to conservatively verify that the requested task is fully completed. Only an affirmative completion verdict sends ✅ Agent run finished.. Incomplete, uncertain, failed or unavailable checks send no finish alert (this can miss a genuine completion; a model cannot guarantee correctness). An aborted run sends ⏹️ Agent run stopped. instead. Pending unsent progress for that run is discarded. Completion verification has a 30-second timeout and may delay the end of the run. If Telegram is not configured, the observer only writes a local diagnostic code when it tries to send.
• The non-overlapping analysis window includes only activity observed since activation. For very dense runs, the full window counts toward the threshold, but the model receives no more than the 24 most recent entries / 12,000 characters of activity; earlier entries are not forwarded. The previous summary (from the same monitoring window) may be included for continuity. The model never extracts conversation messages or tool arguments from before activation.
• Progress is saved as JSONL under ~/.pi/agent/pi-overwatch/<sessionId>.jsonl. Telegram progress reports have concise Chinese section values for the task, overall stage, completed work, current work, issues, and next step; the stage uses plain everyday language. Telegram output is redacted for tokens and secrets. Output lists longer than 10 entries are truncated rather than re-analyzed.
• Failed analyses pause for 60 seconds and retry only after new activity. The sidecar model call has a 45-second timeout; errors remain local diagnostic codes and never interrupt the foreground task. With thinking off, the maximum response length is 1,536 tokens; with minimal or low, 4,096; with higher thinking, 8,192.

A new conversation (including an empty startup) removes old .jsonl and errors.log in ~/.pi/agent/pi-overwatch/; restarting or resuming an existing conversation leaves them intact. Credentials are never deleted by this cleanup.

For development from a local checkout, run npm test and npm pack --dry-run before installing the checkout with pi install <path-to-this-directory>.