claude-code-telegrammer 0.3.0__tar.gz → 0.4.0__tar.gz

{claude_code_telegrammer-0.3.0 → claude_code_telegrammer-0.4.0}/.github/workflows/test.yml

@@ -22,5 +22,18 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -e .
+          pip install pyyaml
       - name: Run shell tests
         run: bash tests/test-state-detection.sh
+
+  test-ts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - name: Install dependencies
+        run: bun install
+        working-directory: ts
+      - name: Run TypeScript tests
+        run: bun test
+        working-directory: ts

claude_code_telegrammer-0.4.0/.gitignore

@@ -0,0 +1 @@
+.mcp.json

claude_code_telegrammer-0.4.0/.readthedocs.yaml

@@ -0,0 +1,31 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/sphinx" directory with Sphinx
+sphinx:
+  configuration: docs/sphinx/conf.py
+  fail_on_warning: false
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+
+# Python configuration
+python:
+  install:
+    # Install package with all optional dependencies
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+    # Install sphinx documentation requirements
+    - requirements: docs/sphinx/requirements.txt

{claude_code_telegrammer-0.3.0 → claude_code_telegrammer-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-telegrammer
-Version: 0.3.0
+Version: 0.4.0
 Summary: Custom Telegram MCP server + TUI auto-responder for running Claude Code as an autonomous Telegram agent
 Project-URL: Homepage, https://github.com/ywatanabe1989/claude-code-telegrammer
 Project-URL: Repository, https://github.com/ywatanabe1989/claude-code-telegrammer.git
@@ -23,10 +23,16 @@ Classifier: Programming Language :: Unix Shell
 Classifier: Topic :: Communications :: Chat
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <!-- ---
-!-- Timestamp: 2026-04-08 18:06:35
+!-- Timestamp: 2026-04-10 18:13:14
 !-- Author: ywatanabe
 !-- File: /home/ywatanabe/proj/claude-code-telegrammer/README.md
 !-- --- -->
@@ -43,235 +49,192 @@ Description-Content-Type: text/markdown
 <p align="center"><b>Custom Telegram MCP server + TUI auto-responder for running Claude Code as an autonomous Telegram agent</b></p>
 
 <p align="center">
+  <a href="https://badge.fury.io/py/claude-code-telegrammer"><img src="https://badge.fury.io/py/claude-code-telegrammer.svg" alt="PyPI version"></a>
+  <a href="https://claude-code-telegrammer.readthedocs.io/"><img src="https://readthedocs.org/projects/claude-code-telegrammer/badge/?version=latest" alt="Documentation"></a>
+  <a href="https://github.com/ywatanabe1989/claude-code-telegrammer/actions/workflows/test.yml"><img src="https://github.com/ywatanabe1989/claude-code-telegrammer/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0"></a>
 </p>
 
----
+<p align="center">
+  <a href="https://claude-code-telegrammer.readthedocs.io/">Documentation</a> ·
+  <code>pip install claude-code-telegrammer</code>
+</p>
 
-## What This Does
+---
 
-Turns Claude Code into a fully autonomous Telegram bot. Two subsystems work together:
+## Problem
 
-1. **Custom Telegram MCP Server** (`ts/`) -- A self-contained MCP server that replaces the broken official `plugin:telegram@claude-plugins-official`. Handles all Telegram Bot API communication, message persistence, attachment handling, and access control.
+The official `plugin:telegram@claude-plugins-official` has several unresolved issues that make it unusable for production autonomous agents:
 
-2. **TUI Watchdog** (`bin/`, `lib/`) -- Polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends keystrokes to keep the agent running unattended (auto-accepts permission prompts, re-engages on idle).
+- **[#851](https://github.com/anthropics/claude-code/issues/851)** -- `STATE_DIR` not respected; access.json path hardcoded
+- **[#1075](https://github.com/anthropics/claude-code/issues/1075)** -- 409 Conflict errors when multiple instances poll the same bot
+- **[#1146](https://github.com/anthropics/claude-code/issues/1146)** -- Zombie CPU consumption after session ends
 
-## Architecture
+Additionally, Claude Code sessions running unattended will stall at permission prompts or idle states with no way to recover.
 
-```
-User (Telegram)
-    |
-    |  Bot API (getUpdates long-polling)
-    v
-┌──────────────────────────────────────────────────────────────┐
-│  Custom Telegram MCP Server (ts/telegram-server.ts)          │
-│    Bun + @modelcontextprotocol/sdk                           │
-│                                                              │
-│    ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌────────────┐    │
-│    │ Poller  │  │  Store  │  │  Tools   │  │ Attachments│    │
-│    │ (long   │  │ (SQLite │  │ (10 MCP  │  │ (download  │    │
-│    │  poll)  │  │  WAL)   │  │  tools)  │  │  queue)    │    │
-│    └─────────┘  └─────────┘  └──────────┘  └────────────┘    │
-│    ┌─────────┐  ┌─────────┐  ┌──────────┐                    │
-│    │ Access  │  │  Config │  │   Lock   │                    │
-│    │ (allow- │  │ (env    │  │ (PID     │                    │
-│    │  list)  │  │  vars)  │  │  file)   │                    │
-│    └─────────┘  └─────────┘  └──────────┘                    │
-└──────────────────────┬───────────────────────────────────────┘
-                       │ MCP stdio
-                       v
-┌──────────────────────────────────────────────────────────────┐
-│  Claude Code (in GNU Screen session)                         │
-│    --channels or --mcp-config points to the MCP server       │
-└──────────────────────┬───────────────────────────────────────┘
-                       │ screen buffer
-                       v
-┌──────────────────────────────────────────────────────────────┐
-│  Watchdog (bin/telegrammer-watchdog)                         │
-│    Polls screen buffer every 1.5s                            │
-│    Detects: y/n prompt -> "1", y/y/n -> "2", idle -> cmd     │
-│    Throttled: burst limit, same-state delay, min interval    │
-└──────────────────────────────────────────────────────────────┘
-```
+## Solution
 
-## Why Custom? (Official Plugin Issues)
+Two subsystems that replace and extend the official plugin:
 
-The official `plugin:telegram@claude-plugins-official` has several unresolved issues that make it unusable for production:
+1. **Custom Telegram MCP Server** (`ts/`) -- A self-contained MCP server that fixes all three official plugin issues: configurable state directory via `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR`, PID-based single-instance lock, and clean shutdown on stdin close/SIGTERM. Provides 10 MCP tools (vs 3 in the official plugin), SQLite message persistence, allowlist-based access control, and inbound reaction (`message_reaction`) delivery. Incoming messages are acknowledged with a 📩 reaction.
 
-- **[#851](https://github.com/anthropics/claude-code/issues/851)** -- `STATE_DIR` not respected; access.json path hardcoded
-- **[#1075](https://github.com/anthropics/claude-code/issues/1075)** -- 409 Conflict errors when multiple instances poll the same bot
-- **[#1146](https://github.com/anthropics/claude-code/issues/1146)** -- Zombie CPU consumption after session ends
+2. **TUI Watchdog** (`lib/`) -- Polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends keystrokes to keep the agent running unattended (auto-accepts permission prompts, re-engages on idle). Throttled with burst limits to prevent runaway responses. Orchestration and lifecycle management is handled by [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
 
-This custom MCP server fixes all three: configurable state directory via `TELEGRAM_STATE_DIR`, PID-based single-instance lock, and clean shutdown on stdin close/SIGTERM.
+<details>
+<summary><strong>MCP Tools (10)</strong></summary>
 
-## Components
+| Tool | Description |
+|------|-------------|
+| `reply` | Reply on Telegram. Supports threading (`reply_to`), auto-marks inbound as read. Inbound reply-to-message references are tracked and forwarded. |
+| `react` | Add an emoji reaction to a message. Inbound reactions (`message_reaction`) are also delivered as channel notifications. |
+| `edit_message` | Edit a previously sent bot message. |
+| `get_history` | Retrieve message history for a chat from local SQLite. |
+| `get_unread` | List unread inbound messages, optionally filtered by `chat_id`. |
+| `mark_read` | Mark messages as read by `chat_id` or `message_ids`. |
+| `download_attachment` | Download a Telegram file by `file_id`, returns local path. |
+| `send_document` | Upload a local file to a Telegram chat. |
+| `search_messages` | Text search across stored messages. |
+| `get_context` | Recent conversation formatted as compact text for LLM context. |
 
-### Custom Telegram MCP Server (`ts/`)
+</details>
 
-A Bun-based MCP server that communicates with the Telegram Bot API directly via `fetch` (no grammy dependency). Connects to Claude Code over stdio using `@modelcontextprotocol/sdk`.
+## Installation
 
-Key files:
-- `ts/telegram-server.ts` -- Entry point, MCP server setup, shutdown handling
-- `ts/lib/poller.ts` -- `getUpdates` long-polling loop with offset persistence
-- `ts/lib/store.ts` -- SQLite message store (schema v2)
-- `ts/lib/tools.ts` -- All 10 MCP tool definitions and handlers
-- `ts/lib/attachments.ts` -- Background download queue (rate-limited, 500ms between downloads)
-- `ts/lib/access.ts` -- Allowlist-based access control with mtime-cached `access.json`
-- `ts/lib/config.ts` -- All configuration constants from environment variables
-- `ts/lib/lock.ts` -- PID-based single-instance enforcement
-- `ts/lib/telegram-api.ts` -- Raw Bot API wrapper
-- `ts/lib/log.ts` -- Structured JSON logging to stderr
+### Prerequisites
 
-### Watchdog (`bin/telegrammer-watchdog`)
+- Python >= 3.10 and GNU Screen (for watchdog/CLI)
+- [Bun](https://bun.sh/) >= 1.0 (for the MCP server)
 
-Polls a GNU Screen session at a configurable interval, detects Claude Code's TUI state via pattern matching, and sends keystrokes.
+### Install
 
 ```bash
-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
+pip install claude-code-telegrammer
 ```
 
-### Hook (`bin/telegrammer-hook`)
-
-Entry point for scitex-agent-container integration. Called by agent-container's lifecycle hooks:
+Or from source:
 
 ```bash
-telegrammer-hook pre-start     # Write access.json, .env, MCP config JSON
-telegrammer-hook post-start    # Start watchdog + send startup commands
-telegrammer-hook pre-stop      # Stop watchdog
+git clone https://github.com/ywatanabe1989/claude-code-telegrammer.git
+cd claude-code-telegrammer
+pip install -e .
+
+# Install TypeScript dependencies for the MCP server
+cd ts && bun install
 ```
 
-The `pre-start` hook handles: bot token mapping (`bot_token_env` -> `TELEGRAM_BOT_TOKEN`), writing `access.json` from YAML `allowed_users`, generating MCP config for `--mcp-config` and `.mcp.json`.
+## Quickstart
 
-### Init (`bin/telegrammer-init`)
+### Get a Telegram Bot Token
 
-Sends startup commands to a running Claude Code screen session and configures `access.json`.
+1. Open Telegram and message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot`, then enter a name (e.g., `Claude Code Telegrammer`) and a username (e.g., `ClaudeCodeTelegrammerBot`)
+3. BotFather replies with your token: `123456789:AAH...`
+4. Verify your token works:
+   ```bash
+   curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
+   # Should return {"ok":true,"result":{"is_bot":true,...}}
+   ```
+5. Open your bot (e.g., [t.me/ClaudeCodeTelegrammerBot](https://t.me/ClaudeCodeTelegrammerBot)) and send any message to start a conversation
+
+### Register MCP Server with Claude Code
+
+Copy the example and fill in your values (`.mcp.json` is gitignored):
+
+```json
+{
+  "mcpServers": {
+    "claude-code-telegrammer": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["run", "/path/to/claude-code-telegrammer/ts/telegram-server.ts"],
+      "env": {
+        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN": "123456789:AAH...",
+        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS": "YOUR_TELEGRAM_USER_ID",
+        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR": "~/.claude-code-telegrammer"
+      }
+    }
+  }
+}
+```
 
 ```bash
-telegrammer-init --session cld-telegram --config telegram-master.yaml
+cp .mcp.json.example .mcp.json
+# Edit .mcp.json with your token, user ID, and paths
 ```
 
-### Guard (`bin/telegrammer-guard`)
+Find your Telegram user ID by messaging [@userinfobot](https://t.me/userinfobot).
 
-Lock/exclusivity guard. Ensures only one telegrammer instance controls a session.
+### Run
 
 ```bash
-telegrammer-guard acquire --lock ~/.scitex/agent-container/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
+claude \
+    --dangerously-skip-permissions \
+    --dangerously-load-development-channels server:claude-code-telegrammer
 ```
 
-### Main CLI (`bin/telegrammer`)
+For full agent orchestration (screen sessions, watchdog, YAML configs), see [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
 
-Full lifecycle management of a Claude Code Telegram agent in a screen session.
+## Interfaces
 
+<details>
+<summary><strong>MCP Server -- for AI Agents</strong></summary>
+
+Start command:
 ```bash
-telegrammer start config/telegram-master.yaml
-telegrammer stop
-telegrammer status
-telegrammer attach
-telegrammer logs
+bun run ts/telegram-server.ts
 ```
 
-## MCP Tools (10)
+10 tools exposed via MCP stdio protocol. See [MCP Tools](#solution) above. The server's MCP instructions include a responsiveness policy that directs the agent to acknowledge messages immediately and delegate heavy work to background subagents.
 
-All tools are exposed via the MCP server and available to Claude Code during a session:
+</details>
 
-| Tool | Description |
-|------|-------------|
-| `reply` | Reply on Telegram. Supports threading (`reply_to`), auto-marks inbound as read, persists outbound to DB. |
-| `react` | Add an emoji reaction to a message. Telegram's fixed whitelist applies. |
-| `edit_message` | Edit a previously sent bot message. Edits don't trigger push notifications. |
-| `get_history` | Retrieve message history (both directions) for a chat from local SQLite. |
-| `get_unread` | List unread inbound messages, optionally filtered by `chat_id`. |
-| `mark_read` | Mark messages as read by `chat_id` (all) or `message_ids` (specific rows). |
-| `download_attachment` | Download a Telegram file by `file_id`, returns local path. |
-| `send_document` | Upload a local file to a Telegram chat via `sendDocument`. |
-| `search_messages` | Text search across stored messages using `LIKE %query%`. |
-| `get_context` | Recent conversation formatted as compact text for LLM context. |
+<details>
+<summary><strong>Skills -- for AI Agent Discovery</strong></summary>
 
-## SQLite Schema (v2)
-
-All messages are persisted in `$TELEGRAM_STATE_DIR/messages.db` using WAL mode.
-
-### `messages` table
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `id` | INTEGER PK | Auto-increment row ID |
-| `direction` | TEXT | `'inbound'` or `'outbound'` |
-| `chat_id` | TEXT | Telegram chat ID |
-| `message_id` | TEXT | Telegram message ID |
-| `user_id` | TEXT | Sender's Telegram user ID |
-| `username` | TEXT | Sender's username |
-| `text` | TEXT | Message content |
-| `telegram_ts` | TEXT | Original Telegram timestamp (ISO 8601) |
-| `received_at` | TEXT | When this server received the message |
-| `read_at` | TEXT | When marked as read (NULL = unread) |
-| `replied_at` | TEXT | When replied to (NULL = unreplied) |
-| `reply_to_message_id` | TEXT | Telegram message ID being replied to |
-| `reply_to_row_id` | INTEGER FK | DB row of inbound message being replied to |
-| `host` | TEXT | Hostname of the machine running the server |
-| `project` | TEXT | Working directory / project path |
-| `agent_id` | TEXT | Agent identifier |
-| `bot_token_hash` | TEXT | First 8 chars of SHA-256 of bot token |
-| `raw_json` | TEXT | Full Telegram update JSON (inbound only) |
-| `created_at` | TEXT | Row creation timestamp |
-
-Key indexes: dedup on `(chat_id, message_id, direction)`, unread index, unreplied index, agent identity index.
-
-### `attachments` table
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `id` | INTEGER PK | Auto-increment |
-| `message_row_id` | INTEGER FK | References `messages(id)` with CASCADE delete |
-| `kind` | TEXT | `photo`, `document`, `voice`, `audio`, `video` |
-| `file_id` | TEXT | Telegram file ID |
-| `file_unique_id` | TEXT | Telegram file unique ID |
-| `file_name` | TEXT | Original filename |
-| `mime_type` | TEXT | MIME type |
-| `file_size` | INTEGER | Size in bytes |
-| `local_path` | TEXT | Local download path (NULL until downloaded) |
-| `downloaded_at` | TEXT | When download completed |
-
-### `meta` table
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `key` | TEXT PK | e.g., `'schema_version'`, `'update_offset'` |
-| `value` | TEXT | Stored value |
-
-## Configuration
-
-### Environment Variables (MCP Server)
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `TELEGRAM_BOT_TOKEN` | Yes | -- | Telegram Bot API token |
-| `TELEGRAM_STATE_DIR` | No | `~/.scitex/agent-container/telegram` | Directory for SQLite DB, access.json, lock file |
-| `TELEGRAM_ALLOWED_USERS` | No | -- | Comma-separated Telegram user IDs for DM allowlist |
-| `TELEGRAM_HOST_NAME` | No | `os.hostname()` | Hostname stored with each message |
-| `TELEGRAM_PROJECT` | No | `process.cwd()` | Project path stored with each message |
-| `TELEGRAM_AGENT_ID` | No | `'telegram'` | Agent identifier stored with each message |
-| `TELEGRAM_ATTACHMENT_DIR` | No | `$TELEGRAM_STATE_DIR/attachments` | Directory for downloaded attachments |
+Skills are bundled at `src/claude_code_telegrammer/_skills/claude-code-telegrammer/SKILL.md`.
 
-### Environment Variables (Watchdog)
+</details>
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `TELEGRAMMER_SESSION` | `cld-telegram` | GNU Screen session name |
-| `TELEGRAMMER_WATCHDOG_INTERVAL` | `1.5` | Poll interval in seconds |
-| `TELEGRAMMER_RESP_Y_N` | `1` | Response for y/n prompts |
-| `TELEGRAMMER_RESP_Y_Y_N` | `2` | Response for y/y/n prompts |
-| `TELEGRAMMER_RESP_WAITING` | `/speak-and-call` | Response when idle/waiting |
+## Architecture
 
-## State Detection
+```
+User (Telegram)
+    |
+    |  Bot API (getUpdates long-polling)
+    v
+┌──────────────────────────────────────────────────────────────┐
+│  Custom Telegram MCP Server (ts/telegram-server.ts)          │
+│    Bun + @modelcontextprotocol/sdk                           │
+│                                                              │
+│    ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌────────────┐    │
+│    │ Poller  │  │  Store  │  │  Tools   │  │ Attachments│    │
+│    │ (long   │  │ (SQLite │  │ (10 MCP  │  │ (download  │    │
+│    │  poll)  │  │  WAL)   │  │  tools)  │  │  queue)    │    │
+│    └─────────┘  └─────────┘  └──────────┘  └────────────┘    │
+│    ┌─────────┐  ┌─────────┐  ┌──────────┐                    │
+│    │ Access  │  │  Config │  │   Lock   │                    │
+│    │ (allow- │  │ (env    │  │ (PID     │                    │
+│    │  list)  │  │  vars)  │  │  file)   │                    │
+│    └─────────┘  └─────────┘  └──────────┘                    │
+└──────────────────────┬───────────────────────────────────────┘
+                       │ MCP stdio
+                       v
+┌──────────────────────────────────────────────────────────────┐
+│  Claude Code (in GNU Screen session)                         │
+│    --mcp-config points to the custom MCP server              │
+└──────────────────────┬───────────────────────────────────────┘
+                       │ screen buffer
+                       v
+┌──────────────────────────────────────────────────────────────┐
+│  Watchdog (claude-code-telegrammer-watchdog)                 │
+│    Polls screen buffer every 1.5s                            │
+│    Detects: y/n prompt -> "1", y/y/n -> "2", idle -> cmd     │
+│    Throttled: burst limit, same-state delay, min interval    │
+└──────────────────────────────────────────────────────────────┘
+```
 
-The watchdog reads the screen buffer and matches against these patterns:
+<details>
+<summary><strong>State Detection</strong></summary>
 
 | State | Pattern | Response |
 |-------|---------|----------|
@@ -282,96 +245,58 @@ The watchdog reads the screen buffer and matches against these patterns:
 
 Response throttling: minimum interval between responses, burst limit (10 in 3s window), same-state delay.
 
-## Integration with scitex-agent-container
-
-Add a `telegram` section and `hooks` to your agent YAML:
-
-```yaml
-apiVersion: telegrammer/v1
-kind: Agent
-metadata:
-  name: telegram-master
-spec:
-  model: opus[1m]
-  flags:
-    - --dangerously-skip-permissions
-    - --strict-mcp-config
-    - "--mcp-config /tmp/scitex-agent-container/mcp-{agent-name}.json"
-    - "--dangerously-load-development-channels server:telegram"
-  workdir: ~/proj
-  env:
-    CLAUDE_AGENT_ROLE: telegram
-    CLAUDE_AGENT_ID: telegram-master
-  telegram:
-    bot_token_env: SCITEX_OROCHI_TELEGRAM_BOT_TOKEN
-    auto_connect: true
-    allowed_users:
-      - 123456789
-  screen:
-    name: cld-telegram
-  watchdog:
-    enabled: true
-    interval: 1.5
-    responses:
-      y_n: "1"
-      y_y_n: "2"
-      waiting: "/speak-and-call"
-  lock:
-    path: ~/.scitex/agent-container/telegram/telegram.lock
-  hooks:
-    pre_start: telegrammer-hook pre-start
-    post_start: telegrammer-hook post-start
-    pre_stop: telegrammer-hook pre-stop
-```
+</details>
 
-The `telegrammer-hook pre-start` phase generates MCP config JSON so Claude Code can discover the custom server via `--mcp-config` or `.mcp.json`.
+<details>
+<summary><strong>Configuration (Environment Variables)</strong></summary>
 
-## Installation
+**MCP Server:**
 
-### Prerequisites
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN` | Yes | -- | Telegram Bot API token |
+| `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR` | No | `~/.claude-code-telegrammer` | Directory for SQLite DB, access.json, lock file |
+| `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS` | No | -- | Comma-separated Telegram user IDs for DM allowlist |
+| `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_HOST_NAME` | No | `os.hostname()` | Hostname stored with each message |
+| `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_PROJECT` | No | `process.cwd()` | Project path stored with each message |
+| `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_AGENT_ID` | No | `'telegram'` | Agent identifier stored with each message |
 
-- Python >= 3.10 and GNU Screen (for watchdog/CLI)
-- [Bun](https://bun.sh/) >= 1.0 (for the MCP server)
+**Watchdog:**
 
-### Install
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_CODE_TELEGRAMMER_SESSION` | `claude-code-telegrammer` | GNU Screen session name |
+| `CLAUDE_CODE_TELEGRAMMER_WATCHDOG_INTERVAL` | `1.5` | Poll interval in seconds |
+| `CLAUDE_CODE_TELEGRAMMER_RESP_Y_N` | `1` | Response for y/n prompts |
+| `CLAUDE_CODE_TELEGRAMMER_RESP_Y_Y_N` | `2` | Response for y/y/n prompts |
+| `CLAUDE_CODE_TELEGRAMMER_RESP_WAITING` | `/speak-and-call` | Response when idle/waiting |
 
-```bash
-pip install claude-code-telegrammer
-```
+</details>
 
-Or from source:
+<details>
+<summary><strong>SQLite Schema (v2)</strong></summary>
 
-```bash
-git clone https://github.com/ywatanabe1989/claude-code-telegrammer.git
-cd claude-code-telegrammer
-pip install -e .
+All messages persisted in `$CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR/messages.db` using WAL mode.
 
-# Install TypeScript dependencies for the MCP server
-cd ts && bun install
-```
+**messages table:** direction, chat_id, message_id, user_id, username, text, timestamps (telegram_ts, received_at, read_at, replied_at), threading (reply_to_message_id, reply_to_row_id), identity (host, project, agent_id, bot_token_hash), raw_json.
 
-## Quick Start
+**attachments table:** message_row_id (FK), kind, file_id, file_name, mime_type, file_size, local_path, downloaded_at.
 
-```bash
-# 1. Export your bot token
-export TELEGRAM_BOT_TOKEN="123456789:AAH..."
+**meta table:** key-value store for schema_version, update_offset.
 
-# 2. Start the MCP server standalone (for testing)
-bun run ts/telegram-server.ts
+</details>
 
-# 3. Or start a full agent with watchdog from a YAML config
-telegrammer start config/telegram-master.yaml
+<details>
+<summary><strong>Integration with scitex-agent-container</strong></summary>
 
-# 4. Check status
-telegrammer status
+For YAML-based agent orchestration (screen sessions, watchdog lifecycle, restart policies), see [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container).
 
-# 5. Attach to the screen session to observe
-screen -r cld-telegram    # Ctrl-A D to detach
-```
+</details>
 
-## Access Control
+<details>
+<summary><strong>Access Control</strong></summary>
 
-Access is managed via `access.json` in `$TELEGRAM_STATE_DIR`:
+Managed via `access.json` in `$CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR`:
 
 ```json
 {
@@ -386,7 +311,9 @@ Access is managed via `access.json` in `$TELEGRAM_STATE_DIR`:
 }
 ```
 
-The allowlist is merged with `TELEGRAM_ALLOWED_USERS` env var at runtime. Mtime-based caching means edits to `access.json` take effect without restart.
+Merged with `CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS` env var at runtime. Mtime-based caching means edits take effect without restart.
+
+</details>
 
 <!-- SciTeX Convention: Ecosystem -->
 ## Part of SciTeX
@@ -409,6 +336,19 @@ claude-code-telegrammer is part of [**SciTeX**](https://scitex.ai). It provides
 └─────────────────────────────────────────────────────────┘
 ```
 
+## References
+
+- [Claude Code Channels](https://docs.anthropic.com/en/docs/claude-code/channels) -- Official documentation for Claude Code's channel system
+- [Official Telegram Plugin](https://github.com/anthropics/claude-code/tree/main/plugins/telegram) -- The `plugin:telegram@claude-plugins-official` source code
+- [#851: STATE_DIR not respected](https://github.com/anthropics/claude-code/issues/851) -- Hardcoded access.json path
+- [#1075: 409 Conflict errors](https://github.com/anthropics/claude-code/issues/1075) -- Multiple instances polling the same bot
+- [#1146: Zombie CPU consumption](https://github.com/anthropics/claude-code/issues/1146) -- Runaway process after session ends
+- [Telegram BotFather](https://t.me/BotFather) -- Create and manage Telegram bots
+- [Telegram Bot API](https://core.telegram.org/bots/api) -- Official Bot API documentation
+- [MCP Specification](https://modelcontextprotocol.io/) -- Model Context Protocol standard
+- [claude-code-telegrammer Issues](https://github.com/ywatanabe1989/claude-code-telegrammer/issues) -- Bug reports and feature requests
+- [claude-code-telegrammer Pull Requests](https://github.com/ywatanabe1989/claude-code-telegrammer/pulls) -- Contributions
+
 <!-- SciTeX Convention: Footer (Four Freedoms + icon) -->
 >Four Freedoms for Research
 >