ClaudeMap

cc-tg-watchdog

Battle-tested watchdog scripts that keep a Claude Code + Telegram session alive on a VPS — auto-restarts, missed-message recovery and credential refresh, checked every 3 minutes.

Plugins & Agentswatchdogtelegramvpslong-runningshell
Visit projectkittenshome/cc-tg-watchdog

Running claude --channels plugin:telegram@claude-plugins-official inside tmux on a VPS eventually hits every failure mode: the tmux process dies quietly, a usage-limit popup wedges the session, the Telegram Bun process disconnects, credentials expire into a 401 loop, context grows until every message burns a fistful of tokens, or a message arrives exactly during the restart. cc-tg-watchdog is a set of shell scripts (watchdog.sh health check, start.sh full restart flow, orphan-recovery.py missed-message detection) wired to a crontab entry that runs every 3 minutes: on failure it kills the old processes, replays messages nobody answered, attempts a credential refresh, starts a fresh tmux session and verifies the Telegram connection. Requirements are modest — tmux, python3, flock, timeout and ss — and the README strongly recommends a dedicated CLAUDE_CONFIG_DIR so the watchdog never touches your normal Claude Code sessions. Chinese-language docs. MIT.

What it does

  • Cron-driven health check every 3 minutes; healthy runs are no-ops, so the watchdog stays out of the way
  • Six failure modes handled: silent tmux death, quota-popup wedges, Bun disconnects, 401 expiry loops, runaway context, messages lost mid-restart
  • orphan-recovery.py scans the session log for messages nobody answered and replays them into the new session
  • Safety rails: dedicated CLAUDE_CONFIG_DIR recommended, and explicit warnings never to commit credentials or session JSONL

When to use it

Anyone running Claude Code as a 24/7 Telegram bot on a cheap VPS — the set-it-up-once-and-forget use case where nobody is watching the terminal when the quota popup lands at 4 a.m.

Getting started

cp watchdog.sh ~/tgbot-watchdog.sh
cp start.sh ~/tgbot.sh
cp orphan-recovery.py ~/tgbot-orphan.py
chmod +x ~/tgbot-watchdog.sh ~/tgbot.sh

crontab -e
# add:
*/3 * * * * /root/tgbot-watchdog.sh

Things to know

The author states up front that this is a script set from one personal environment — not an official Anthropic or Telegram component, and not guaranteed loss-free. Default thresholds and process signatures can shift with Claude Code or plugin versions, so validate on a test bot before trusting it in production. It manages sessions via process inspection, so unusual launch setups may need threshold tweaks. MIT.

Repository

kittenshome/cc-tg-watchdog

Charted

Related on the map

  • CometixCode

    Plugin / Agent

    An unofficial Rust 1:1 reimplementation of the Claude Code terminal UI, ported file-for-file onto an iocraft TUI framework.

    • terminal-ui
    • rust
    • reimplementation
    • unofficial
    View

  • Abide

    Plugin / Agent

    Hook-level enforcement for the natural-language rules in AGENTS.md and CLAUDE.md — every edit is judged and violations are repaired in the same turn.

    • hooks
    • code-review
    • rules
    • agents-md
    View

  • fast-jev-compaction

    Plugin / Agent

    A Claude Code plugin that replaces the lossy compaction summary with Jev-scored pruning: stale tool calls are dropped, and everything kept stays verbatim.

    • plugin
    • context-management
    • compaction
    • function-hooks
    View