feat: improve polling behavior with infinite loop by default

- `tg updates poll` without --timeout now loops indefinitely with 50s
  internal timeout until updates arrive
- `tg updates poll --timeout N` performs a single poll (for hooks/scripts)
- Updated skill documentation and hook scripts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: danizord

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-01-04
+
+### Changed
+
+- `tg updates poll` without `--timeout` now loops indefinitely with 50s internal timeout until updates arrive
+- `tg updates poll --timeout N` performs a single poll (useful for hooks and scripts)
+- Updated polling documentation and examples to reflect new behavior
+
 ## [0.1.0] - 2026-01-04
 
 ### Added
@@ -37,4 +45,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - GitHub Actions CI workflow with type checking, linting, and tests
 - Modern tooling: tsgo, oxlint, oxfmt
 
+[0.2.0]: https://github.com/danizord/telecli/releases/tag/v0.2.0
 [0.1.0]: https://github.com/danizord/telecli/releases/tag/v0.1.0

package.json

@@ -1,6 +1,6 @@
 {
   "name": "telecli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Thin CLI wrapper around the Telegram Bot API",
   "type": "module",
   "bin": {

plugin/commands/telegram-poll.md

@@ -25,10 +25,11 @@ Start or stop the Telegram polling loop.
 2. Confirm polling has started
 
 3. Begin the polling loop:
-   - Run `tg updates poll --timeout 30` (or with `--offset` if resuming)
+   - Run `tg updates poll` (or with `--offset` if resuming)
+   - The command will poll indefinitely with 50s timeout until updates arrive
    - Process any incoming messages (respond, react, etc.)
    - Update `last_offset` in state file with highest update_id + 1
-   - Continue polling
+   - Run the poll command again to wait for more updates
 
 ## Stopping Polling
 

plugin/hooks/scripts/check-updates.sh

@@ -40,7 +40,7 @@ if echo "$result" | grep -qF '"update_id"'; then
 {
   "decision": "block",
   "reason": "New Telegram messages received",
-  "systemMessage": "New Telegram updates received. Process these messages:\n\n\`\`\`json\n$updates\n\`\`\`\n\nRespond to any messages that need a response, then continue polling with: tg updates poll --timeout 30 --offset $new_offset"
+  "systemMessage": "New Telegram updates received. Process these messages:\n\n\`\`\`json\n$updates\n\`\`\`\n\nRespond to any messages that need a response, then continue polling with: tg updates poll --offset $new_offset"
 }
 EOF
 else

plugin/skills/telecli/SKILL.md

@@ -37,18 +37,18 @@ tg config path           # Show config file paths
 ### Polling for Updates
 
 ```bash
-# Basic poll (returns immediately if no updates)
+# Wait indefinitely for updates (loops with 50s timeout until updates arrive)
 tg updates poll
 
-# Long polling with timeout (waits up to N seconds)
-tg updates poll --timeout 30
+# With offset (skip already-processed updates)
+tg updates poll --offset 729538157
 
-# Poll with offset (skip already-processed updates)
-tg updates poll --timeout 30 --offset 729538157
+# Single poll with explicit timeout (for scripts/hooks)
+tg updates poll --timeout 5
 ```
 
 **Polling loop pattern:**
-1. Call `tg updates poll --timeout 30`
+1. Call `tg updates poll` (blocks until updates arrive)
 2. Process returned messages
 3. Calculate next offset: `max(update_id) + 1`
 4. Repeat with `--offset <next_offset>`
@@ -178,7 +178,8 @@ tg message send "$chat_id" "You said: $text" --reply-to "$message_id"
 ```bash
 offset=""
 while true; do
-  result=$(tg updates poll --timeout 30 $offset)
+  # Blocks until updates arrive (no --timeout = infinite polling)
+  result=$(tg updates poll $offset)
 
   # Process updates
   echo "$result" | jq -c '.result[]' | while read update; do

src/index.ts

@@ -495,13 +495,30 @@ async function main() {
         const subcommand = positional[0];
         switch (subcommand) {
           case "poll": {
-            output(
-              await getUpdates({
-                offset: flags.offset ? parseInt(flags.offset) : undefined,
-                limit: flags.limit ? parseInt(flags.limit) : undefined,
-                timeout: flags.timeout ? parseInt(flags.timeout) : undefined,
-              }),
-            );
+            const offset = flags.offset ? parseInt(flags.offset) : undefined;
+            const limit = flags.limit ? parseInt(flags.limit) : undefined;
+
+            // If --timeout is explicitly provided, do a single poll (for hooks)
+            // If omitted, loop forever with 50s timeout until updates arrive
+            if (flags.timeout !== undefined) {
+              output(
+                await getUpdates({
+                  offset,
+                  limit,
+                  timeout: parseInt(flags.timeout),
+                }),
+              );
+            } else {
+              // Loop forever until we get updates
+              while (true) {
+                const result = await getUpdates({ offset, limit, timeout: 50 });
+                if (result.ok && result.result && result.result.length > 0) {
+                  output(result);
+                  break;
+                }
+                // If no updates, continue polling (don't output empty results)
+              }
+            }
             break;
           }
           case "webhook": {