ctb 1.1.0 → 1.2.1

package/README.md

@@ -38,12 +38,15 @@ To achieve this, I set up a folder with a CLAUDE.md that teaches Claude about me
 # Install globally
 npm install -g ctb
 
+# Show setup tutorial
+ctb tut
+
 # Run in any project directory
 cd ~/my-project
 ctb
 ```
 
-On first run, `ctb` will prompt for your Telegram bot token and allowed user IDs, then optionally save them to `.env`.
+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.
 
 **Run multiple instances:** Each project directory gets its own isolated bot session. Open multiple terminals and run `ctb` in different directories.
 
@@ -102,8 +105,17 @@ new - Start a fresh session
 resume - Resume last session
 stop - Interrupt current query
 status - Check what Claude is doing
+model - Switch model (sonnet, opus, haiku)
+cost - Show token usage and estimated cost
+think - Force thinking mode
+plan - Toggle planning mode
+compact - Trigger context compaction
+undo - Revert file changes to last checkpoint
 cd - Change working directory
+skill - Invoke a Claude Code skill
+file - Download a file
 bookmarks - Manage directory bookmarks
+retry - Retry last message
 restart - Restart the bot
 ```
 
@@ -148,16 +160,35 @@ The bot includes a built-in `ask_user` MCP server that lets Claude present optio
 
 ## Bot Commands
 
-| Command      | Description                       |
-| ------------ | --------------------------------- |
-| `/start`     | Show status and your user ID      |
-| `/new`       | Start a fresh session             |
-| `/resume`    | Resume last session after restart |
-| `/stop`      | Interrupt current query           |
-| `/status`    | Check what Claude is doing        |
-| `/cd <path>` | Change working directory          |
-| `/bookmarks` | Manage directory bookmarks        |
-| `/restart`   | Restart the bot                   |
+| Command         | Description                                                |
+| --------------- | ---------------------------------------------------------- |
+| `/start`        | Show status and your user ID                               |
+| `/new`          | Start a fresh session                                      |
+| `/resume`       | Resume last session after restart                          |
+| `/stop`         | Interrupt current query (aliases: `/c`, `/kill`, `/dc`)    |
+| `/status`       | Check what Claude is doing                                 |
+| `/model <name>` | Switch model: sonnet, opus, haiku                          |
+| `/cost`         | Show token usage and estimated cost                        |
+| `/think [lvl]`  | Force thinking: off, normal, deep (default)                |
+| `/plan`         | Toggle planning mode (no tool execution)                   |
+| `/compact`      | Trigger context compaction                                 |
+| `/undo`         | Revert file changes to last checkpoint                     |
+| `/cd <path>`    | Change working directory                                   |
+| `/skill <name>` | Invoke a Claude Code skill (e.g., `/skill commit`)         |
+| `/file [path]`  | Download file (auto-detects from last response if no path) |
+| `/bookmarks`    | Manage directory bookmarks                                 |
+| `/retry`        | Retry last message                                         |
+| `/restart`      | Restart the bot                                            |
+
+### Shell Commands
+
+Prefix any message with `!` to run it as a shell command in the working directory:
+
+```
+!ls -la
+!git status
+!pwd
+```
 
 ### Directory Navigation
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ctb",
-	"version": "1.1.0",
+	"version": "1.2.1",
 	"description": "Control Claude Code from Telegram - run multiple bot instances per project",
 	"type": "module",
 	"bin": {

package/src/__tests__/cli.test.ts

@@ -180,6 +180,7 @@ describe("CLI argument parsing", () => {
 		dir?: string;
 		help?: boolean;
 		version?: boolean;
+		tut?: boolean;
 	} {
 		const options: {
 			token?: string;
@@ -187,6 +188,7 @@ describe("CLI argument parsing", () => {
 			dir?: string;
 			help?: boolean;
 			version?: boolean;
+			tut?: boolean;
 		} = {};
 
 		for (const arg of args) {
@@ -194,6 +196,8 @@ describe("CLI argument parsing", () => {
 				options.help = true;
 			} else if (arg === "--version" || arg === "-v") {
 				options.version = true;
+			} else if (arg === "tut" || arg === "tutorial") {
+				options.tut = true;
 			} else if (arg.startsWith("--token=")) {
 				options.token = arg.slice(8);
 			} else if (arg.startsWith("--users=")) {
@@ -222,6 +226,14 @@ describe("CLI argument parsing", () => {
 		expect(parseArgs(["-v"])).toEqual({ version: true });
 	});
 
+	test("parses tut command", () => {
+		expect(parseArgs(["tut"])).toEqual({ tut: true });
+	});
+
+	test("parses tutorial command", () => {
+		expect(parseArgs(["tutorial"])).toEqual({ tut: true });
+	});
+
 	test("parses --token option", () => {
 		const result = parseArgs(["--token=my-bot-token"]);
 		expect(result.token).toBe("my-bot-token");

package/src/__tests__/session.test.ts

@@ -0,0 +1,399 @@
+/**
+ * Unit tests for session module - model, cost, thinking, and plan mode features.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { ClaudeSession, getThinkingLevel } from "../session";
+
+describe("getThinkingLevel", () => {
+	// Default keywords from config.ts:
+	// THINKING_KEYWORDS: "think,pensa,ragiona"
+	// THINKING_DEEP_KEYWORDS: "ultrathink,think hard,pensa bene"
+
+	describe("deep thinking triggers", () => {
+		test("triggers on 'think hard'", () => {
+			expect(getThinkingLevel("Please think hard about this")).toBe(50000);
+		});
+
+		test("triggers on 'ultrathink'", () => {
+			expect(getThinkingLevel("ultrathink about the problem")).toBe(50000);
+		});
+
+		test("triggers on 'pensa bene' (Italian)", () => {
+			expect(getThinkingLevel("pensa bene prima di rispondere")).toBe(50000);
+		});
+
+		test("is case insensitive", () => {
+			expect(getThinkingLevel("THINK HARD about this")).toBe(50000);
+			expect(getThinkingLevel("ULTRATHINK")).toBe(50000);
+		});
+	});
+
+	describe("normal thinking triggers", () => {
+		test("triggers on 'think'", () => {
+			expect(getThinkingLevel("Let me think about this")).toBe(10000);
+		});
+
+		test("triggers on 'pensa' (Italian)", () => {
+			expect(getThinkingLevel("pensa a questo problema")).toBe(10000);
+		});
+
+		test("triggers on 'ragiona' (Italian)", () => {
+			expect(getThinkingLevel("ragiona sul codice")).toBe(10000);
+		});
+
+		test("is case insensitive", () => {
+			expect(getThinkingLevel("THINK about it")).toBe(10000);
+			expect(getThinkingLevel("PENSA attentamente")).toBe(10000);
+		});
+	});
+
+	describe("no thinking triggers", () => {
+		test("returns 0 for simple messages", () => {
+			expect(getThinkingLevel("Hello")).toBe(0);
+			expect(getThinkingLevel("What time is it?")).toBe(0);
+			expect(getThinkingLevel("Show me the file")).toBe(0);
+		});
+
+		test("returns 0 for empty string", () => {
+			expect(getThinkingLevel("")).toBe(0);
+		});
+
+		test("returns 0 for unrelated words", () => {
+			expect(getThinkingLevel("analyze this code")).toBe(0);
+			expect(getThinkingLevel("consider the options")).toBe(0);
+			expect(getThinkingLevel("evaluate this approach")).toBe(0);
+		});
+	});
+
+	describe("priority", () => {
+		test("deep triggers take precedence over normal", () => {
+			// "think hard" should trigger deep (50000), not normal "think" (10000)
+			expect(getThinkingLevel("think hard")).toBe(50000);
+		});
+	});
+});
+
+describe("ClaudeSession", () => {
+	let session: ClaudeSession;
+
+	beforeEach(() => {
+		session = new ClaudeSession();
+	});
+
+	describe("model selection", () => {
+		test("defaults to sonnet", () => {
+			expect(session.currentModel).toBe("sonnet");
+		});
+
+		test("can be set to opus", () => {
+			session.currentModel = "opus";
+			expect(session.currentModel).toBe("opus");
+		});
+
+		test("can be set to haiku", () => {
+			session.currentModel = "haiku";
+			expect(session.currentModel).toBe("haiku");
+		});
+
+		test("can switch between models", () => {
+			session.currentModel = "opus";
+			expect(session.currentModel).toBe("opus");
+
+			session.currentModel = "haiku";
+			expect(session.currentModel).toBe("haiku");
+
+			session.currentModel = "sonnet";
+			expect(session.currentModel).toBe("sonnet");
+		});
+	});
+
+	describe("forceThinking", () => {
+		test("defaults to null", () => {
+			expect(session.forceThinking).toBeNull();
+		});
+
+		test("can be set to specific token count", () => {
+			session.forceThinking = 10000;
+			expect(session.forceThinking).toBe(10000);
+		});
+
+		test("can be set to 0 (off)", () => {
+			session.forceThinking = 0;
+			expect(session.forceThinking).toBe(0);
+		});
+
+		test("can be set to deep (50000)", () => {
+			session.forceThinking = 50000;
+			expect(session.forceThinking).toBe(50000);
+		});
+	});
+
+	describe("planMode", () => {
+		test("defaults to false", () => {
+			expect(session.planMode).toBe(false);
+		});
+
+		test("can be toggled on", () => {
+			session.planMode = true;
+			expect(session.planMode).toBe(true);
+		});
+
+		test("can be toggled off", () => {
+			session.planMode = true;
+			session.planMode = false;
+			expect(session.planMode).toBe(false);
+		});
+	});
+
+	describe("token usage tracking", () => {
+		test("starts with zero totals", () => {
+			expect(session.totalInputTokens).toBe(0);
+			expect(session.totalOutputTokens).toBe(0);
+			expect(session.totalCacheReadTokens).toBe(0);
+		});
+
+		test("can accumulate input tokens", () => {
+			session.totalInputTokens += 1000;
+			session.totalInputTokens += 500;
+			expect(session.totalInputTokens).toBe(1500);
+		});
+
+		test("can accumulate output tokens", () => {
+			session.totalOutputTokens += 2000;
+			session.totalOutputTokens += 800;
+			expect(session.totalOutputTokens).toBe(2800);
+		});
+
+		test("can accumulate cache read tokens", () => {
+			session.totalCacheReadTokens += 500;
+			session.totalCacheReadTokens += 300;
+			expect(session.totalCacheReadTokens).toBe(800);
+		});
+	});
+
+	describe("estimateCost", () => {
+		describe("sonnet pricing", () => {
+			test("calculates zero cost for zero tokens", () => {
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(0);
+				expect(cost.outputCost).toBe(0);
+				expect(cost.total).toBe(0);
+			});
+
+			test("calculates cost for 1M input tokens", () => {
+				session.totalInputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(3); // $3 per 1M input
+				expect(cost.outputCost).toBe(0);
+				expect(cost.total).toBe(3);
+			});
+
+			test("calculates cost for 1M output tokens", () => {
+				session.totalOutputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(0);
+				expect(cost.outputCost).toBe(15); // $15 per 1M output
+				expect(cost.total).toBe(15);
+			});
+
+			test("calculates combined cost", () => {
+				session.totalInputTokens = 500_000;
+				session.totalOutputTokens = 100_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(1.5); // $3 * 0.5
+				expect(cost.outputCost).toBe(1.5); // $15 * 0.1
+				expect(cost.total).toBe(3);
+			});
+		});
+
+		describe("opus pricing", () => {
+			beforeEach(() => {
+				session.currentModel = "opus";
+			});
+
+			test("calculates cost for 1M input tokens", () => {
+				session.totalInputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(15); // $15 per 1M input
+			});
+
+			test("calculates cost for 1M output tokens", () => {
+				session.totalOutputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.outputCost).toBe(75); // $75 per 1M output
+			});
+
+			test("calculates combined cost", () => {
+				session.totalInputTokens = 100_000;
+				session.totalOutputTokens = 50_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(1.5); // $15 * 0.1
+				expect(cost.outputCost).toBe(3.75); // $75 * 0.05
+				expect(cost.total).toBe(5.25);
+			});
+		});
+
+		describe("haiku pricing", () => {
+			beforeEach(() => {
+				session.currentModel = "haiku";
+			});
+
+			test("calculates cost for 1M input tokens", () => {
+				session.totalInputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(0.25); // $0.25 per 1M input
+			});
+
+			test("calculates cost for 1M output tokens", () => {
+				session.totalOutputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.outputCost).toBe(1.25); // $1.25 per 1M output
+			});
+
+			test("calculates combined cost", () => {
+				session.totalInputTokens = 4_000_000;
+				session.totalOutputTokens = 800_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(1); // $0.25 * 4
+				expect(cost.outputCost).toBe(1); // $1.25 * 0.8
+				expect(cost.total).toBe(2);
+			});
+		});
+
+		describe("small token counts", () => {
+			test("calculates fractional costs", () => {
+				session.totalInputTokens = 1000;
+				session.totalOutputTokens = 500;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBeCloseTo(0.003, 5); // $3 * 0.001
+				expect(cost.outputCost).toBeCloseTo(0.0075, 5); // $15 * 0.0005
+				expect(cost.total).toBeCloseTo(0.0105, 5);
+			});
+		});
+	});
+
+	describe("kill", () => {
+		test("resets sessionId", async () => {
+			session.sessionId = "test-session-123";
+			await session.kill();
+			expect(session.sessionId).toBeNull();
+		});
+
+		test("resets lastActivity", async () => {
+			session.lastActivity = new Date();
+			await session.kill();
+			expect(session.lastActivity).toBeNull();
+		});
+
+		test("resets token totals", async () => {
+			session.totalInputTokens = 10000;
+			session.totalOutputTokens = 5000;
+			session.totalCacheReadTokens = 2000;
+			await session.kill();
+			expect(session.totalInputTokens).toBe(0);
+			expect(session.totalOutputTokens).toBe(0);
+			expect(session.totalCacheReadTokens).toBe(0);
+		});
+
+		test("resets planMode", async () => {
+			session.planMode = true;
+			await session.kill();
+			expect(session.planMode).toBe(false);
+		});
+
+		test("resets forceThinking", async () => {
+			session.forceThinking = 50000;
+			await session.kill();
+			expect(session.forceThinking).toBeNull();
+		});
+
+		test("preserves currentModel", async () => {
+			session.currentModel = "opus";
+			await session.kill();
+			expect(session.currentModel).toBe("opus");
+		});
+	});
+
+	describe("isActive", () => {
+		test("returns false when no sessionId", () => {
+			expect(session.isActive).toBe(false);
+		});
+
+		test("returns true when sessionId exists", () => {
+			session.sessionId = "test-session-123";
+			expect(session.isActive).toBe(true);
+		});
+	});
+
+	describe("workingDir", () => {
+		test("can get working directory", () => {
+			expect(typeof session.workingDir).toBe("string");
+		});
+
+		test("setWorkingDir changes directory", () => {
+			const newDir = "/tmp/test-dir";
+			session.setWorkingDir(newDir);
+			expect(session.workingDir).toBe(newDir);
+		});
+
+		test("setWorkingDir clears sessionId", () => {
+			session.sessionId = "test-session-123";
+			session.setWorkingDir("/tmp/new-dir");
+			expect(session.sessionId).toBeNull();
+		});
+	});
+
+	describe("stop", () => {
+		test("returns false when nothing is running", async () => {
+			const result = await session.stop();
+			expect(result).toBe(false);
+		});
+	});
+
+	describe("interrupt flags", () => {
+		test("markInterrupt and consumeInterruptFlag work together", () => {
+			expect(session.consumeInterruptFlag()).toBe(false);
+			session.markInterrupt();
+			expect(session.consumeInterruptFlag()).toBe(true);
+			expect(session.consumeInterruptFlag()).toBe(false); // Consumed
+		});
+	});
+
+	describe("processing state", () => {
+		test("startProcessing returns cleanup function", () => {
+			expect(session.isRunning).toBe(false);
+			const cleanup = session.startProcessing();
+			expect(session.isRunning).toBe(true);
+			cleanup();
+			expect(session.isRunning).toBe(false);
+		});
+	});
+
+	describe("undo/checkpointing", () => {
+		test("canUndo is false by default", () => {
+			expect(session.canUndo).toBe(false);
+		});
+
+		test("undoCheckpoints is 0 by default", () => {
+			expect(session.undoCheckpoints).toBe(0);
+		});
+
+		test("undo fails when no session active", async () => {
+			const [success, message] = await session.undo();
+			expect(success).toBe(false);
+			expect(message).toContain("No active session");
+		});
+
+		test("kill resets checkpoints", async () => {
+			// Simulate having checkpoints (by accessing private property for testing)
+			// @ts-expect-error - accessing private for test
+			session._userMessageUuids = ["uuid1", "uuid2"];
+			expect(session.undoCheckpoints).toBe(2);
+
+			await session.kill();
+			expect(session.undoCheckpoints).toBe(0);
+			expect(session.canUndo).toBe(false);
+		});
+	});
+});

package/src/bot.ts

@@ -18,17 +18,24 @@ import {
 	handleBookmarks,
 	handleCallback,
 	handleCd,
+	handleCompact,
+	handleCost,
 	handleDocument,
+	handleFile,
+	handleModel,
 	handleNew,
 	handlePhoto,
-	handlePreview,
+	handlePlan,
 	handleRestart,
 	handleResume,
 	handleRetry,
+	handleSkill,
 	handleStart,
 	handleStatus,
 	handleStop,
 	handleText,
+	handleThink,
+	handleUndo,
 	handleVoice,
 } from "./handlers";
 
@@ -61,12 +68,22 @@ bot.use(
 bot.command("start", handleStart);
 bot.command("new", handleNew);
 bot.command("stop", handleStop);
+bot.command("c", handleStop);
+bot.command("kill", handleStop);
+bot.command("dc", handleStop);
 bot.command("status", handleStatus);
 bot.command("resume", handleResume);
 bot.command("restart", handleRestart);
 bot.command("retry", handleRetry);
 bot.command("cd", handleCd);
-bot.command("preview", handlePreview);
+bot.command("skill", handleSkill);
+bot.command("file", handleFile);
+bot.command("model", handleModel);
+bot.command("cost", handleCost);
+bot.command("think", handleThink);
+bot.command("plan", handlePlan);
+bot.command("compact", handleCompact);
+bot.command("undo", handleUndo);
 bot.command("bookmarks", handleBookmarks);
 
 // ============== Message Handlers ==============
@@ -113,8 +130,15 @@ await bot.api.setMyCommands([
 	{ command: "resume", description: "Resume last session" },
 	{ command: "stop", description: "Interrupt current query" },
 	{ command: "status", description: "Check what Claude is doing" },
+	{ command: "model", description: "Switch model (sonnet/opus/haiku)" },
+	{ command: "cost", description: "Show token usage and cost" },
+	{ command: "think", description: "Force extended thinking" },
+	{ command: "plan", description: "Toggle planning mode" },
+	{ command: "compact", description: "Trigger context compaction" },
+	{ command: "undo", description: "Revert file changes" },
 	{ command: "cd", description: "Change working directory" },
-	{ command: "preview", description: "Download a file" },
+	{ command: "skill", description: "Invoke a Claude Code skill" },
+	{ command: "file", description: "Download a file" },
 	{ command: "bookmarks", description: "Manage directory bookmarks" },
 	{ command: "retry", description: "Retry last message" },
 	{ command: "restart", description: "Restart the bot" },