claude-code-telegrammer 0.2.0

Screen-based auto-responder watchdog for Claude Code TUI

claude-code-telegrammer

Screen-based auto-responder watchdog for Claude Code TUI

---

Problem

Claude Code's TUI blocks on permission prompts (y/n, y/y/n) and goes idle after completing tasks. Running Claude Code as an autonomous agent -- for example, as a Telegram bot -- requires something to detect these states and respond automatically, or the agent stalls within seconds.

Solution

claude-code-telegrammer polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends the appropriate keystrokes to keep the agent running unattended. No modifications to Claude Code itself -- just screen buffer inspection and keystroke injection.

Claude Code (in screen)
    |
    +-- telegrammer-watchdog polls screen buffer every 1.5s
    |       |
    |       +-- Detects "y/n" prompt  --> sends "1" (accept)
    |       +-- Detects "y/y/n" prompt --> sends "2" (accept all)
    |       +-- Detects idle/waiting   --> sends "/speak-and-call"
    |
    +-- telegrammer-guard ensures single instance via lock file

Installation

Requires Python >= 3.10 and GNU Screen.

pip install claude-code-telegrammer

Or install from source:

git clone https://github.com/ywatanabe1989/claude-code-telegrammer.git
cd claude-code-telegrammer
pip install -e .

Quickstart

# Start an agent from a YAML config
telegrammer start --config config/telegram-master.yaml

# Check status
telegrammer status

# Attach to the screen session to observe
screen -r cld-telegram    # Ctrl-A D to detach

Components

telegrammer

Main CLI entry point. Manages the full lifecycle of a Claude Code Telegram agent in a screen session.

telegrammer start --config telegram-master.yaml
telegrammer stop
telegrammer status
telegrammer restart

telegrammer-watchdog

The core auto-responder. Polls a screen session at a configurable interval, detects Claude Code's TUI state, and sends keystrokes.

telegrammer-watchdog --session cld-telegram --interval 1.5
telegrammer-watchdog --dry-run          # detect without responding
telegrammer-watchdog --self-test        # run built-in state detection tests

telegrammer-guard

Lock/exclusivity guard. Ensures only one telegrammer instance controls a session at a time.

telegrammer-guard acquire --lock ~/.claude/channels/telegram/telegram.lock
telegrammer-guard release
telegrammer-guard status
telegrammer-guard check     # exit 0 if locked, 1 if not
telegrammer-guard force     # force-remove lock

telegrammer-init

Sends startup commands to a running Claude Code screen session and optionally configures Telegram access.json.

telegrammer-init --session cld-telegram --config telegram-master.yaml

State Detection

The watchdog reads the screen buffer and matches against these patterns:

State	Pattern	Response
Permission prompt (y/n)	Claude asking for single approval	Send 1 (yes)
Permission prompt (y/y/n)	Claude asking with "yes to all" option	Send 2 (yes to all)
Idle / waiting	Agent completed task, waiting for input	Send /speak-and-call

Responses are configurable via YAML or environment variables:

export TELEGRAMMER_RESP_Y_N="1"
export TELEGRAMMER_RESP_Y_Y_N="2"
export TELEGRAMMER_RESP_WAITING="/speak-and-call"

Configuration

apiVersion: telegrammer/v1
kind: Agent
metadata:
  name: telegram-master
spec:
  model: opus[1m]
  channels:
    - plugin:telegram@claude-plugins-official
  flags:
    - --dangerously-skip-permissions
    - --continue
  workdir: ~/proj
  env:
    CLAUDE_AGENT_ROLE: telegram
    CLAUDE_AGENT_ID: telegram-master
  screen:
    name: cld-telegram
  watchdog:
    enabled: true
    interval: 1.5
    responses:
      y_n: "1"
      y_y_n: "2"
      waiting: "/speak-and-call"
  lock:
    path: ~/.claude/channels/telegram/telegram.lock
  restart:
    enabled: false
    max_retries: 3
    backoff: exponential

Part of SciTeX

claude-code-telegrammer is part of SciTeX. It is the low-level watchdog engine used by scitex-agent-container for higher-level agent lifecycle management.

pip install scitex-agent-container[telegram]

When used together, scitex-agent-container handles lifecycle management (health checks, restart policies, hooks) while claude-code-telegrammer handles the screen-level auto-response.

Four Freedoms for Research

0. The freedom to run your research anywhere -- your machine, your terms.
1. The freedom to study how every step works -- from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 -- because we believe research infrastructure deserves the same freedoms as the software it runs on.

---