telegram-claude-mcp 1.6.0 → 2.0.1

package/ARCHITECTURE.md

@@ -0,0 +1,234 @@
+# Architecture Options for Multi-Session MCP
+
+This document describes three approaches for handling multiple Claude Code sessions with a shared Telegram bot.
+
+## Current Architecture (Baseline)
+
+```
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Server 1 (port 3333)           │
+│                 │                │  ├─ TelegramManager (polling)       │──►┌──────────┐
+│                 │                │  └─ HTTP Hook Server                │   │          │
+└─────────────────┘                └─────────────────────────────────────┘   │          │
+                                                                             │ Telegram │
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐   │   Bot    │
+│  Claude Code 2  │◄──────────────►│  MCP Server 2 (port 3334)           │   │          │
+│                 │                │  ├─ TelegramManager (polling)       │──►│          │
+│                 │                │  └─ HTTP Hook Server                │   └──────────┘
+└─────────────────┘                └─────────────────────────────────────┘
+
+Hook scripts discover ports via /tmp/telegram-claude-sessions/*.info files
+```
+
+**Problems:**
+- Multiple bot polling instances (potential rate limiting)
+- Port collision handling complexity
+- Session discovery via filesystem
+- Each process manages its own state
+
+---
+
+## Option 1: Proxy Pattern (Recommended)
+
+A singleton daemon handles all Telegram communication. Thin MCP proxies forward requests.
+
+```
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     ┌─────────────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Proxy 1    │◄───────────────────►│                             │
+│                 │                │  (session: proj1)│                     │     Singleton Daemon        │
+└─────────────────┘                └─────────────────┘                     │     (single process)        │
+                                                                           │                             │
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     │  ├─ TelegramManager         │──►┌──────────┐
+│  Claude Code 2  │◄──────────────►│  MCP Proxy 2    │◄───────────────────►│  │  (single polling)        │   │ Telegram │
+│                 │                │  (session: proj2)│                     │  ├─ SessionManager          │   │   Bot    │
+└─────────────────┘                └─────────────────┘                     │  │  (tracks all sessions)   │   └──────────┘
+                                                                           │  └─ HTTP Hook Server        │
+                                   ┌─────────────────┐     HTTP POST       │     (single port: 3333)     │
+                                   │  Hook Scripts   │────────────────────►│                             │
+                                   └─────────────────┘                     └─────────────────────────────┘
+```
+
+### Components
+
+**1. Singleton Daemon (`telegram-claude-daemon`)**
+- Single long-running process
+- Manages one TelegramManager with single bot polling
+- Exposes Unix socket for proxy connections
+- Exposes single HTTP port for all hooks
+- Tracks all active sessions in memory
+- Routes messages to correct session
+
+**2. MCP Proxy (`telegram-claude-proxy`)**
+- Spawned by Claude Code (stdio transport)
+- Connects to daemon via Unix socket
+- Registers session with unique ID
+- Forwards MCP tool calls to daemon
+- Receives responses from daemon
+
+### Protocol (Daemon <-> Proxy)
+
+```typescript
+// Proxy -> Daemon
+interface ProxyMessage {
+  type: 'connect' | 'disconnect' | 'tool_call';
+  sessionId: string;
+  sessionName: string;
+  payload?: {
+    tool: string;
+    arguments: Record<string, unknown>;
+  };
+}
+
+// Daemon -> Proxy
+interface DaemonMessage {
+  type: 'connected' | 'tool_result' | 'error';
+  sessionId: string;
+  payload?: {
+    result?: unknown;
+    error?: string;
+  };
+}
+```
+
+### Advantages
+- Single bot polling (no rate limiting)
+- Single port for hooks (no discovery needed)
+- Centralized session management
+- Clean separation of concerns
+- Daemon can outlive individual sessions
+
+### Disadvantages
+- Requires daemon to be running before Claude Code starts
+- Additional IPC complexity
+- Single point of failure
+
+### Implementation Files
+```
+server/src/
+├── daemon/
+│   ├── index.ts          # Daemon entry point
+│   ├── session-manager.ts # Track active sessions
+│   └── ipc-server.ts     # Unix socket server
+├── proxy/
+│   ├── index.ts          # Proxy entry point (MCP stdio)
+│   └── ipc-client.ts     # Unix socket client
+└── shared/
+    └── protocol.ts       # Shared types and constants
+```
+
+---
+
+## Option 2: Shared State Pattern
+
+Keep MCP-per-session but share Telegram connection via IPC to a daemon.
+
+```
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Server 1                       │
+│                 │                │  ├─ Full MCP implementation         │
+│                 │                │  ├─ HTTP Hook Server (port 3333)    │───┐
+└─────────────────┘                │  └─ IPC Client                      │   │
+                                   └─────────────────────────────────────┘   │
+                                                    │                        │
+                                                    │ IPC (send/receive)     │ HTTP
+                                                    ▼                        │
+                                   ┌─────────────────────────────────────┐   │
+                                   │  Telegram Daemon                    │   │
+                                   │  ├─ TelegramManager (single poll)  │──►┌──────────┐
+                                   │  └─ Message Router                  │   │ Telegram │
+                                   └─────────────────────────────────────┘   │   Bot    │
+                                                    ▲                        └──────────┘
+                                                    │ IPC (send/receive)
+                                                    │
+┌─────────────────┐     stdio      ┌─────────────────────────────────────┐
+│  Claude Code 2  │◄──────────────►│  MCP Server 2                       │
+│                 │                │  ├─ Full MCP implementation         │
+│                 │                │  ├─ HTTP Hook Server (port 3334)    │
+│                 │                │  └─ IPC Client                      │
+└─────────────────┘                └─────────────────────────────────────┘
+```
+
+### How It Works
+1. Each MCP server maintains its own HTTP hook server
+2. Telegram operations are forwarded to a shared daemon
+3. Daemon handles actual Telegram API calls
+4. Responses routed back via IPC
+
+### Advantages
+- MCP servers remain mostly unchanged
+- Gradual migration path
+- Each session still has its own hook endpoint
+
+### Disadvantages
+- Still requires port management for hooks
+- More complex message routing
+- Partial duplication of logic
+
+---
+
+## Option 3: Session ID in Tool Calls
+
+Single MCP server process, sessions identified by explicit IDs in every tool call.
+
+```
+┌─────────────────┐                              ┌─────────────────────────────┐
+│  Claude Code 1  │──┐                           │                             │
+│                 │  │   Multiple stdio          │  Singleton MCP Server       │
+└─────────────────┘  │   connections via         │                             │
+                     │   wrapper/multiplexer     │  ├─ TelegramManager         │──►┌──────────┐
+┌─────────────────┐  │                           │  ├─ SessionManager          │   │ Telegram │
+│  Claude Code 2  │──┼──────────────────────────►│  └─ HTTP Hook Server        │   │   Bot    │
+│                 │  │                           │                             │   └──────────┘
+└─────────────────┘  │                           │  Tools include session_id:  │
+                     │                           │  - send_message(session_id) │
+┌─────────────────┐  │                           │  - continue_chat(session_id)│
+│  Claude Code 3  │──┘                           │                             │
+└─────────────────┘                              └─────────────────────────────┘
+```
+
+### How It Works
+1. Single MCP server handles all sessions
+2. `connect` tool registers new session, returns session_id
+3. All other tools require session_id parameter
+4. Server routes operations by session_id
+
+### Challenges
+- MCP's stdio transport is 1:1 (one client per process)
+- Would need a multiplexer/wrapper to share one MCP server
+- Violates MCP design assumptions
+- Complex error handling when sessions disconnect
+
+### Advantages
+- Simplest daemon architecture
+- Single process for everything
+
+### Disadvantages
+- Requires custom MCP multiplexer
+- Not standard MCP usage
+- Harder to implement correctly
+
+---
+
+## Comparison Matrix
+
+| Aspect                    | Current      | Option 1 (Proxy)  | Option 2 (Shared) | Option 3 (Session ID) |
+|---------------------------|--------------|-------------------|-------------------|----------------------|
+| Bot polling instances     | N            | 1                 | 1                 | 1                    |
+| Port management           | Complex      | Simple (1 port)   | Complex           | Simple (1 port)      |
+| MCP compatibility         | Standard     | Standard          | Standard          | Non-standard         |
+| Implementation effort     | Done         | Medium            | Medium-High       | High                 |
+| Session isolation         | Full         | Full              | Full              | Logical only         |
+| Daemon dependency         | No           | Yes               | Yes               | Yes                  |
+| Hook simplicity           | Medium       | Simple            | Medium            | Simple               |
+
+---
+
+## Recommended: Option 1 (Proxy Pattern)
+
+Option 1 provides the best balance of:
+- **Simplicity**: Single port, single polling instance
+- **Compatibility**: Standard MCP stdio transport
+- **Reliability**: Clean session management
+- **Maintainability**: Clear separation between proxy and daemon
+
+The proxy is lightweight and only handles MCP protocol translation, while the daemon manages all Telegram complexity.

package/README.md

@@ -35,29 +35,29 @@ Create directory `~/.claude/hooks/` and add these scripts:
 **~/.claude/hooks/permission-hook.sh**
 ```bash
 #!/bin/bash
+# Set SESSION_NAME env var to target a specific session (for multi-session setups)
 SESSION_DIR="/tmp/telegram-claude-sessions"
 
-find_active_session() {
-  local latest_file=""
-  local latest_time=0
+find_session() {
+  if [ -n "$SESSION_NAME" ]; then
+    local f="$SESSION_DIR/${SESSION_NAME}.info"
+    [ -f "$f" ] && { local p=$(jq -r '.pid // empty' "$f" 2>/dev/null); [ -n "$p" ] && kill -0 "$p" 2>/dev/null && echo "$f"; return; }
+    return
+  fi
+  local latest="" latest_time=0
   [ -d "$SESSION_DIR" ] || return
-  for info_file in "$SESSION_DIR"/*.info; do
-    [ -e "$info_file" ] || continue
-    local pid
-    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
-    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
-      local file_time
-      file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
-      if [ "$file_time" -gt "$latest_time" ]; then
-        latest_time=$file_time
-        latest_file=$info_file
-      fi
-    fi
+  for f in "$SESSION_DIR"/*.info; do
+    [ -e "$f" ] || continue
+    local p=$(jq -r '.pid // empty' "$f" 2>/dev/null)
+    [ -n "$p" ] && kill -0 "$p" 2>/dev/null && {
+      local t=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null)
+      [ "$t" -gt "$latest_time" ] && { latest_time=$t; latest=$f; }
+    }
   done
-  echo "$latest_file"
+  echo "$latest"
 }
 
-INFO_FILE=$(find_active_session)
+INFO_FILE=$(find_session)
 [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
 
 HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
@@ -78,33 +78,33 @@ RESPONSE=$(curl -s -X POST "$HOOK_URL" -H "Content-Type: application/json" -d "$
 **~/.claude/hooks/stop-hook.sh**
 ```bash
 #!/bin/bash
+# Set SESSION_NAME env var to target a specific session (for multi-session setups)
 SESSION_DIR="/tmp/telegram-claude-sessions"
 
-find_active_session() {
-  local latest_file=""
-  local latest_time=0
+find_session() {
+  if [ -n "$SESSION_NAME" ]; then
+    local f="$SESSION_DIR/${SESSION_NAME}.info"
+    [ -f "$f" ] && { local p=$(jq -r '.pid // empty' "$f" 2>/dev/null); [ -n "$p" ] && kill -0 "$p" 2>/dev/null && echo "$f"; return; }
+    return
+  fi
+  local latest="" latest_time=0
   [ -d "$SESSION_DIR" ] || return
-  for info_file in "$SESSION_DIR"/*.info; do
-    [ -e "$info_file" ] || continue
-    local pid
-    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
-    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
-      local file_time
-      file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
-      if [ "$file_time" -gt "$latest_time" ]; then
-        latest_time=$file_time
-        latest_file=$info_file
-      fi
-    fi
+  for f in "$SESSION_DIR"/*.info; do
+    [ -e "$f" ] || continue
+    local p=$(jq -r '.pid // empty' "$f" 2>/dev/null)
+    [ -n "$p" ] && kill -0 "$p" 2>/dev/null && {
+      local t=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null)
+      [ "$t" -gt "$latest_time" ] && { latest_time=$t; latest=$f; }
+    }
   done
-  echo "$latest_file"
+  echo "$latest"
 }
 
 INPUT=$(cat)
 STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
 [ "$STOP_HOOK_ACTIVE" = "true" ] && exit 0
 
-INFO_FILE=$(find_active_session)
+INFO_FILE=$(find_session)
 [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
 
 HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
@@ -124,29 +124,29 @@ fi
 **~/.claude/hooks/notify-hook.sh**
 ```bash
 #!/bin/bash
+# Set SESSION_NAME env var to target a specific session (for multi-session setups)
 SESSION_DIR="/tmp/telegram-claude-sessions"
 
-find_active_session() {
-  local latest_file=""
-  local latest_time=0
+find_session() {
+  if [ -n "$SESSION_NAME" ]; then
+    local f="$SESSION_DIR/${SESSION_NAME}.info"
+    [ -f "$f" ] && { local p=$(jq -r '.pid // empty' "$f" 2>/dev/null); [ -n "$p" ] && kill -0 "$p" 2>/dev/null && echo "$f"; return; }
+    return
+  fi
+  local latest="" latest_time=0
   [ -d "$SESSION_DIR" ] || return
-  for info_file in "$SESSION_DIR"/*.info; do
-    [ -e "$info_file" ] || continue
-    local pid
-    pid=$(jq -r '.pid // empty' "$info_file" 2>/dev/null)
-    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
-      local file_time
-      file_time=$(stat -f %m "$info_file" 2>/dev/null || stat -c %Y "$info_file" 2>/dev/null)
-      if [ "$file_time" -gt "$latest_time" ]; then
-        latest_time=$file_time
-        latest_file=$info_file
-      fi
-    fi
+  for f in "$SESSION_DIR"/*.info; do
+    [ -e "$f" ] || continue
+    local p=$(jq -r '.pid // empty' "$f" 2>/dev/null)
+    [ -n "$p" ] && kill -0 "$p" 2>/dev/null && {
+      local t=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null)
+      [ "$t" -gt "$latest_time" ] && { latest_time=$t; latest=$f; }
+    }
   done
-  echo "$latest_file"
+  echo "$latest"
 }
 
-INFO_FILE=$(find_active_session)
+INFO_FILE=$(find_session)
 [ -z "$INFO_FILE" ] || [ ! -f "$INFO_FILE" ] && exit 0
 
 HOOK_PORT=$(jq -r '.port' "$INFO_FILE")
@@ -175,19 +175,19 @@ Add to `~/.claude/settings.json`:
     "PermissionRequest": [
       {
         "matcher": "*",
-        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-hook.sh" }]
+        "hooks": [{ "type": "command", "command": "SESSION_NAME=default ~/.claude/hooks/permission-hook.sh" }]
       }
     ],
     "Stop": [
       {
         "matcher": "*",
-        "hooks": [{ "type": "command", "command": "~/.claude/hooks/stop-hook.sh" }]
+        "hooks": [{ "type": "command", "command": "SESSION_NAME=default ~/.claude/hooks/stop-hook.sh" }]
       }
     ],
     "Notification": [
       {
         "matcher": "*",
-        "hooks": [{ "type": "command", "command": "~/.claude/hooks/notify-hook.sh" }]
+        "hooks": [{ "type": "command", "command": "SESSION_NAME=default ~/.claude/hooks/notify-hook.sh" }]
       }
     ]
   },
@@ -205,6 +205,8 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
+**Important:** The `SESSION_NAME` in hook commands must match the `SESSION_NAME` in the MCP server env.
+
 ### 3. Create Telegram Bot
 
 1. Open Telegram and message [@BotFather](https://t.me/BotFather)
@@ -257,17 +259,84 @@ Claude Code                    Hook Scripts                 telegram-claude-mcp
 
 ## Multiple Sessions
 
-Run multiple Claude instances with different session names:
+Run multiple Claude Code instances (e.g., `~/.claude` and `~/.claude-personal`) with proper message routing.
+
+### Why This Matters
+
+Without proper configuration, hooks from one Claude session might route to another session's MCP server. The `SESSION_NAME` environment variable ensures each session connects to its own MCP server.
+
+### Configuration
+
+Each Claude config needs a unique `SESSION_NAME` in **both** the MCP server env and the hook commands.
+
+**~/.claude/settings.json** (main):
+```json
+{
+  "hooks": {
+    "PermissionRequest": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks/permission-hook.sh" }]
+    }],
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks/stop-hook.sh" }]
+    }],
+    "Notification": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks/notify-hook.sh" }]
+    }]
+  },
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "telegram-claude-mcp"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
+        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID",
+        "SESSION_NAME": "main"
+      }
+    }
+  }
+}
+```
 
+**~/.claude-personal/settings.json** (personal):
 ```json
 {
-  "env": {
-    "SESSION_NAME": "project-a"
+  "hooks": {
+    "PermissionRequest": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=personal ~/.claude/hooks/permission-hook.sh" }]
+    }],
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=personal ~/.claude/hooks/stop-hook.sh" }]
+    }],
+    "Notification": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=personal ~/.claude/hooks/notify-hook.sh" }]
+    }]
+  },
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "telegram-claude-mcp"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
+        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID",
+        "SESSION_NAME": "personal"
+      }
+    }
   }
 }
 ```
 
-Messages are tagged with `[project-a]` so you know which instance sent them.
+### Key Points
+
+- **SESSION_NAME must match** - The env var in hook commands must match the MCP server's SESSION_NAME
+- **Share hook scripts** - All configs can use the same hook scripts in `~/.claude/hooks/`
+- **Message tagging** - Messages are tagged with `[main]` or `[personal]` so you know the source
+- **Separate ports** - Each MCP server auto-discovers an available port
 
 ## Troubleshooting
 
@@ -284,6 +353,128 @@ Messages are tagged with `[project-a]` so you know which instance sent them.
 - Verify hook scripts are executable: `ls -la ~/.claude/hooks/`
 - Check Claude settings have hooks configured
 
+---
+
+## v2: Daemon Architecture (Recommended for Multiple Sessions)
+
+Version 2 introduces a singleton daemon architecture that handles all Telegram communication from one process. This solves:
+- Multiple bot polling instances causing rate limiting
+- Complex port discovery between sessions
+- Session state synchronization issues
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed design documentation.
+
+### Quick Start with Daemon
+
+**Option A: Auto-start (recommended)**
+
+The proxy can auto-start the daemon if you provide credentials in the MCP config:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "telegram-claude-proxy"],
+      "env": {
+        "SESSION_NAME": "main",
+        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
+        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID"
+      }
+    }
+  }
+}
+```
+
+The first Claude session will start the daemon automatically. Subsequent sessions connect to the already-running daemon.
+
+**Option B: Manual daemon start**
+
+Start the daemon once, then proxies connect without needing credentials:
+
+```bash
+# Start daemon with credentials
+TELEGRAM_BOT_TOKEN=xxx TELEGRAM_CHAT_ID=yyy telegram-claude-ctl start
+
+# Check status
+telegram-claude-ctl status
+```
+
+2. **Configure Claude to use the proxy** in `~/.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "PermissionRequest": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks-v2/permission-hook.sh" }]
+    }],
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks-v2/stop-hook.sh" }]
+    }],
+    "Notification": [{
+      "matcher": "*",
+      "hooks": [{ "type": "command", "command": "SESSION_NAME=main ~/.claude/hooks-v2/notify-hook.sh" }]
+    }]
+  },
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "telegram-claude-proxy"],
+      "env": {
+        "SESSION_NAME": "main"
+      }
+    }
+  }
+}
+```
+
+### Daemon Commands
+
+```bash
+# Start daemon in background
+telegram-claude-ctl start
+
+# Stop daemon
+telegram-claude-ctl stop
+
+# Restart daemon
+telegram-claude-ctl restart
+
+# Check status (shows active sessions)
+telegram-claude-ctl status
+```
+
+### Architecture Overview
+
+```
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     ┌─────────────────────┐
+│  Claude Code 1  │◄──────────────►│  MCP Proxy 1    │◄───────────────────►│                     │
+└─────────────────┘                └─────────────────┘                     │  Singleton Daemon   │
+                                                                           │                     │
+┌─────────────────┐     stdio      ┌─────────────────┐     Unix Socket     │  - Single bot poll  │──► Telegram
+│  Claude Code 2  │◄──────────────►│  MCP Proxy 2    │◄───────────────────►│  - Session manager  │
+└─────────────────┘                └─────────────────┘                     │  - HTTP hooks :3333 │
+                                                                           └─────────────────────┘
+```
+
+### Environment Variables (Daemon)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | Required |
+| `TELEGRAM_CHAT_ID` | Your Telegram chat ID | Required |
+| `CHAT_RESPONSE_TIMEOUT_MS` | Response timeout | 600000 (10 min) |
+| `PERMISSION_TIMEOUT_MS` | Permission timeout | 600000 (10 min) |
+
+### Environment Variables (Proxy/Hooks)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SESSION_NAME` | Session identifier | Auto-detected from CWD |
+| `TELEGRAM_CLAUDE_PORT` | Daemon HTTP port | 3333 |
+| `TELEGRAM_CLAUDE_HOST` | Daemon host | localhost |
+
 ## License
 
 MIT