ctb 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/README.md +50 -11
  2. package/docs/plans/2026-02-01-performance-reliability-improvements.md +1038 -0
  3. package/package.json +1 -1
  4. package/src/__tests__/cli.test.ts +12 -0
  5. package/src/__tests__/errors.test.ts +60 -0
  6. package/src/__tests__/events.test.ts +43 -0
  7. package/src/__tests__/session.test.ts +472 -0
  8. package/src/__tests__/telegram-api.test.ts +80 -0
  9. package/src/bot.ts +27 -3
  10. package/src/cli.ts +94 -0
  11. package/src/errors.ts +58 -0
  12. package/src/events.ts +57 -0
  13. package/src/handlers/commands.ts +383 -50
  14. package/src/handlers/index.ts +8 -1
  15. package/src/handlers/streaming.ts +23 -27
  16. package/src/handlers/text.ts +2 -1
  17. package/src/index.ts +53 -18
  18. package/src/session.ts +207 -7
  19. package/src/telegram-api.ts +195 -0
  20. package/src/types.ts +34 -33
  21. package/src/utils.ts +4 -21
package/README.md CHANGED
@@ -38,12 +38,15 @@ To achieve this, I set up a folder with a CLAUDE.md that teaches Claude about me
38
38
  # Install globally
39
39
  npm install -g ctb
40
40
 
41
+ # Show setup tutorial
42
+ ctb tut
43
+
41
44
  # Run in any project directory
42
45
  cd ~/my-project
43
46
  ctb
44
47
  ```
45
48
 
46
- On first run, `ctb` will prompt for your Telegram bot token and allowed user IDs, then optionally save them to `.env`.
49
+ On first run, `ctb` will prompt for your Telegram bot token and allowed user IDs, then optionally save them to `.env`. Run `ctb tut` for a step-by-step setup guide.
47
50
 
48
51
  **Run multiple instances:** Each project directory gets its own isolated bot session. Open multiple terminals and run `ctb` in different directories.
49
52
 
@@ -102,8 +105,17 @@ new - Start a fresh session
102
105
  resume - Resume last session
103
106
  stop - Interrupt current query
104
107
  status - Check what Claude is doing
108
+ model - Switch model (sonnet, opus, haiku)
109
+ cost - Show token usage and estimated cost
110
+ think - Force thinking mode
111
+ plan - Toggle planning mode
112
+ compact - Trigger context compaction
113
+ undo - Revert file changes to last checkpoint
105
114
  cd - Change working directory
115
+ skill - Invoke a Claude Code skill
116
+ file - Download a file
106
117
  bookmarks - Manage directory bookmarks
118
+ retry - Retry last message
107
119
  restart - Restart the bot
108
120
  ```
109
121
 
@@ -148,16 +160,35 @@ The bot includes a built-in `ask_user` MCP server that lets Claude present optio
148
160
 
149
161
  ## Bot Commands
150
162
 
151
- | Command | Description |
152
- | ------------ | --------------------------------- |
153
- | `/start` | Show status and your user ID |
154
- | `/new` | Start a fresh session |
155
- | `/resume` | Resume last session after restart |
156
- | `/stop` | Interrupt current query |
157
- | `/status` | Check what Claude is doing |
158
- | `/cd <path>` | Change working directory |
159
- | `/bookmarks` | Manage directory bookmarks |
160
- | `/restart` | Restart the bot |
163
+ | Command | Description |
164
+ | --------------- | ---------------------------------------------------------- |
165
+ | `/start` | Show status and your user ID |
166
+ | `/new` | Start a fresh session |
167
+ | `/resume` | Resume last session after restart |
168
+ | `/stop` | Interrupt current query (aliases: `/c`, `/kill`, `/dc`) |
169
+ | `/status` | Check what Claude is doing |
170
+ | `/model <name>` | Switch model: sonnet, opus, haiku |
171
+ | `/cost` | Show token usage and estimated cost |
172
+ | `/think [lvl]` | Force thinking: off, normal, deep (default) |
173
+ | `/plan` | Toggle planning mode (no tool execution) |
174
+ | `/compact` | Trigger context compaction |
175
+ | `/undo` | Revert file changes to last checkpoint |
176
+ | `/cd <path>` | Change working directory |
177
+ | `/skill <name>` | Invoke a Claude Code skill (e.g., `/skill commit`) |
178
+ | `/file [path]` | Download file (auto-detects from last response if no path) |
179
+ | `/bookmarks` | Manage directory bookmarks |
180
+ | `/retry` | Retry last message |
181
+ | `/restart` | Restart the bot |
182
+
183
+ ### Shell Commands
184
+
185
+ Prefix any message with `!` to run it as a shell command in the working directory:
186
+
187
+ ```
188
+ !ls -la
189
+ !git status
190
+ !pwd
191
+ ```
161
192
 
162
193
  ### Directory Navigation
163
194
 
@@ -231,6 +262,14 @@ Multiple layers protect against misuse:
231
262
  5. **Rate limiting** - Prevents runaway usage
232
263
  6. **Audit logging** - All interactions logged to `/tmp/claude-telegram-audit.log`
233
264
 
265
+ ## Reliability Features
266
+
267
+ - **Debounced session persistence** - Reduces disk I/O by batching session saves
268
+ - **Automatic retry** - Transient Telegram API errors are retried with exponential backoff
269
+ - **Graceful shutdown** - Clean shutdown with timeout ensures session data is saved
270
+ - **Session versioning** - Prevents loading incompatible session data after updates
271
+ - **Friendly errors** - Technical errors are translated to helpful user messages
272
+
234
273
  ## Troubleshooting
235
274
 
236
275
  **Bot doesn't respond**