ctb 1.1.0 → 1.2.1

package/src/cli.ts

@@ -23,6 +23,7 @@ interface CliOptions {
 	dir?: string;
 	help?: boolean;
 	version?: boolean;
+	tut?: boolean;
 }
 
 function parseArgs(args: string[]): CliOptions {
@@ -33,6 +34,8 @@ function parseArgs(args: string[]): CliOptions {
 			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=")) {
@@ -53,6 +56,7 @@ Run a Telegram bot that controls Claude Code in your project directory.
 
 USAGE:
   ctb [options]
+  ctb tut              Show setup tutorial
 
 OPTIONS:
   --help, -h       Show this help message
@@ -75,6 +79,91 @@ Multiple instances can run simultaneously in different directories.
 `);
 }
 
+function showTutorial(): void {
+	console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║                    CTB Setup Tutorial                            ║
+╚══════════════════════════════════════════════════════════════════╝
+
+Follow these steps to set up your Claude Telegram Bot:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 1: Create a Telegram Bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Open Telegram and search for @BotFather
+2. Send /newbot
+3. Follow the prompts:
+   - Choose a name (e.g., "My Claude Bot")
+   - Choose a username (must end in "bot", e.g., "my_claude_bot")
+4. Copy the token that looks like:
+   1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 2: Get Your Telegram User ID
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Open Telegram and search for @userinfobot
+2. Send any message to it
+3. It will reply with your user ID (a number like 123456789)
+4. Copy this number
+
+   Tip: Add multiple user IDs separated by commas for team access
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 3: Configure the Bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Option A: Interactive setup (easiest)
+  Just run: ctb
+  It will prompt you for the token and user IDs.
+
+Option B: Create a .env file
+  Create a file named .env in your project directory:
+
+  TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+  TELEGRAM_ALLOWED_USERS=123456789,987654321
+
+Option C: Use command-line arguments
+  ctb --token=YOUR_TOKEN --users=YOUR_USER_ID
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 4: Set Up Bot Commands (Optional)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Go back to @BotFather
+2. Send /setcommands
+3. Select your bot
+4. Paste this command list:
+
+start - Show status and user ID
+new - Start a fresh session
+resume - Resume last session
+stop - Interrupt current query
+status - Check what Claude is doing
+undo - Revert file changes
+cd - Change working directory
+file - Download a file
+bookmarks - Manage directory bookmarks
+retry - Retry last message
+restart - Restart the bot
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 5: Start the Bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  cd ~/your-project
+  ctb
+
+The bot will start and show "Bot started: @your_bot_username"
+Open Telegram and message your bot to start using Claude!
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Need help? https://github.com/htlin/claude-telegram-bot
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`);
+}
+
 async function prompt(question: string): Promise<string> {
 	const rl = createInterface({
 		input: process.stdin,
@@ -226,6 +315,11 @@ async function main(): Promise<void> {
 		process.exit(0);
 	}
 
+	if (options.tut) {
+		showTutorial();
+		process.exit(0);
+	}
+
 	// Determine working directory
 	const workingDir = options.dir ? resolve(options.dir) : process.cwd();
 

package/src/handlers/commands.ts

@@ -11,6 +11,7 @@ import { isBookmarked, loadBookmarks, resolvePath } from "../bookmarks";
 import { ALLOWED_USERS, RESTART_FILE } from "../config";
 import { isAuthorized, isPathAllowed } from "../security";
 import { session } from "../session";
+import { startTypingIndicator } from "../utils";
 
 /**
  * /start - Show welcome message and status.
@@ -37,7 +38,7 @@ export async function handleStart(ctx: Context): Promise<void> {
 			`/resume - Resume last session\n` +
 			`/retry - Retry last message\n` +
 			`/cd - Change working directory\n` +
-			`/preview - Download a file\n` +
+			`/file - Download a file\n` +
 			`/bookmarks - Manage directory bookmarks\n` +
 			`/restart - Restart the bot\n\n` +
 			`<b>Tips:</b>\n` +
@@ -71,7 +72,24 @@ export async function handleNew(ctx: Context): Promise<void> {
 	// Clear session
 	await session.kill();
 
-	await ctx.reply("🆕 Session cleared. Next message starts fresh.");
+	// Get context info
+	const username = process.env.USER || process.env.USERNAME || "unknown";
+	const workDir = session.workingDir;
+	const now = new Date().toLocaleString("en-US", {
+		weekday: "short",
+		month: "short",
+		day: "numeric",
+		hour: "2-digit",
+		minute: "2-digit",
+	});
+
+	await ctx.reply(
+		`🆕 Session cleared. Next message starts fresh.\n\n` +
+			`👤 ${username}\n` +
+			`📁 <code>${workDir}</code>\n` +
+			`🕐 ${now}`,
+		{ parse_mode: "HTML" },
+	);
 }
 
 /**
@@ -275,6 +293,267 @@ export async function handleRetry(ctx: Context): Promise<void> {
 	await handleText(fakeCtx);
 }
 
+/**
+ * /skill - Invoke a Claude Code skill.
+ */
+export async function handleSkill(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	// Get the skill name and args from command
+	const text = ctx.message?.text || "";
+	const match = text.match(/^\/skill\s+(\S+)(?:\s+(.*))?$/);
+
+	if (!match) {
+		await ctx.reply(
+			`🎯 <b>Invoke Skill</b>\n\n` +
+				`Usage: <code>/skill &lt;name&gt; [args]</code>\n\n` +
+				`Examples:\n` +
+				`• <code>/skill commit</code>\n` +
+				`• <code>/skill review-pr 123</code>\n` +
+				`• <code>/skill map</code>`,
+			{ parse_mode: "HTML" },
+		);
+		return;
+	}
+
+	const skillName = match[1] ?? "";
+	const skillArgs = match[2] || "";
+
+	// Build the skill command (Claude Code format: /skill_name args)
+	const skillCommand = skillArgs
+		? `/${skillName} ${skillArgs}`
+		: `/${skillName}`;
+
+	// Send to Claude via handleText
+	const { handleText } = await import("./text");
+	const fakeCtx = {
+		...ctx,
+		message: {
+			...ctx.message,
+			text: skillCommand,
+		},
+	} as Context;
+
+	await handleText(fakeCtx);
+}
+
+/**
+ * /model - Switch between models.
+ */
+export async function handleModel(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	const text = ctx.message?.text || "";
+	const match = text.match(/^\/model\s+(\w+)$/i);
+
+	if (!match) {
+		const current = session.currentModel;
+		await ctx.reply(
+			`🤖 <b>Model Selection</b>\n\n` +
+				`Current: <b>${current}</b>\n\n` +
+				`Usage: <code>/model &lt;name&gt;</code>\n\n` +
+				`Available:\n` +
+				`• <code>/model sonnet</code> - Fast, balanced\n` +
+				`• <code>/model opus</code> - Most capable\n` +
+				`• <code>/model haiku</code> - Fastest, cheapest`,
+			{ parse_mode: "HTML" },
+		);
+		return;
+	}
+
+	const modelName = match[1]?.toLowerCase();
+	if (modelName !== "sonnet" && modelName !== "opus" && modelName !== "haiku") {
+		await ctx.reply(
+			`❌ Unknown model: ${modelName}\n\nUse: sonnet, opus, or haiku`,
+		);
+		return;
+	}
+
+	session.currentModel = modelName;
+	await ctx.reply(`🤖 Switched to <b>${modelName}</b>`, { parse_mode: "HTML" });
+}
+
+/**
+ * /cost - Show token usage and estimated cost.
+ */
+export async function handleCost(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	const cost = session.estimateCost();
+	const formatNum = (n: number) => n.toLocaleString();
+	const formatCost = (n: number) => `$${n.toFixed(4)}`;
+
+	await ctx.reply(
+		`💰 <b>Session Usage</b>\n\n` +
+			`Model: <b>${session.currentModel}</b>\n\n` +
+			`<b>Tokens:</b>\n` +
+			`• Input: ${formatNum(session.totalInputTokens)}\n` +
+			`• Output: ${formatNum(session.totalOutputTokens)}\n` +
+			`• Cache read: ${formatNum(session.totalCacheReadTokens)}\n\n` +
+			`<b>Estimated Cost:</b>\n` +
+			`• Input: ${formatCost(cost.inputCost)}\n` +
+			`• Output: ${formatCost(cost.outputCost)}\n` +
+			`• Total: <b>${formatCost(cost.total)}</b>`,
+		{ parse_mode: "HTML" },
+	);
+}
+
+/**
+ * /think - Force extended thinking for next message.
+ */
+export async function handleThink(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	const text = ctx.message?.text || "";
+	const match = text.match(/^\/think\s+(\w+)$/i);
+
+	let tokens: number;
+	let label: string;
+
+	if (!match) {
+		// Default to deep thinking
+		tokens = 50000;
+		label = "deep (50K tokens)";
+	} else {
+		const level = match[1]?.toLowerCase();
+		if (level === "off" || level === "0") {
+			tokens = 0;
+			label = "off";
+		} else if (level === "normal" || level === "10k") {
+			tokens = 10000;
+			label = "normal (10K tokens)";
+		} else if (level === "deep" || level === "50k") {
+			tokens = 50000;
+			label = "deep (50K tokens)";
+		} else {
+			await ctx.reply(`❌ Unknown level: ${level}\n\nUse: off, normal, deep`);
+			return;
+		}
+	}
+
+	session.forceThinking = tokens;
+	await ctx.reply(`🧠 Next message will use <b>${label}</b> thinking`, {
+		parse_mode: "HTML",
+	});
+}
+
+/**
+ * /plan - Toggle planning mode.
+ */
+export async function handlePlan(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	session.planMode = !session.planMode;
+
+	if (session.planMode) {
+		await ctx.reply(
+			`📋 <b>Plan mode ON</b>\n\n` +
+				`Claude will analyze and plan without executing tools.\n` +
+				`Use <code>/plan</code> again to exit.`,
+			{ parse_mode: "HTML" },
+		);
+	} else {
+		await ctx.reply(`📋 Plan mode OFF - Normal execution resumed`);
+	}
+}
+
+/**
+ * /compact - Request context compaction (sends a hint to Claude).
+ */
+export async function handleCompact(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	if (!session.isActive) {
+		await ctx.reply("❌ No active session to compact.");
+		return;
+	}
+
+	// Send a message that triggers Claude to compact
+	const { handleText } = await import("./text");
+	const fakeCtx = {
+		...ctx,
+		message: {
+			...ctx.message,
+			text: "/compact",
+		},
+	} as Context;
+
+	await handleText(fakeCtx);
+}
+
+/**
+ * /undo - Revert file changes to last checkpoint.
+ */
+export async function handleUndo(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	if (!session.isActive) {
+		await ctx.reply("❌ No active session.");
+		return;
+	}
+
+	if (!session.canUndo) {
+		await ctx.reply(
+			`❌ No checkpoints available.\n\n` +
+				`Checkpoints are created when you send messages.`,
+		);
+		return;
+	}
+
+	// Show progress
+	const typing = startTypingIndicator(ctx);
+	const statusMsg = await ctx.reply("⏪ Reverting files...");
+
+	try {
+		const [success, message] = await session.undo();
+
+		// Update status message with result
+		await ctx.api.editMessageText(
+			ctx.chat!.id,
+			statusMsg.message_id,
+			success ? message : `❌ ${message}`,
+			{ parse_mode: "HTML" },
+		);
+	} finally {
+		typing.stop();
+	}
+}
+
 /**
  * /cd - Change working directory.
  */
@@ -352,81 +631,135 @@ export async function handleCd(ctx: Context): Promise<void> {
 }
 
 /**
- * /preview - Send a file to the user.
+ * Send a single file to the user. Returns error message or null on success.
  */
-export async function handlePreview(ctx: Context): Promise<void> {
-	const userId = ctx.from?.id;
-
-	if (!isAuthorized(userId, ALLOWED_USERS)) {
-		await ctx.reply("Unauthorized.");
-		return;
-	}
-
-	// Get the path argument from command
-	const text = ctx.message?.text || "";
-	const match = text.match(/^\/preview\s+(.+)$/);
-
-	if (!match) {
-		await ctx.reply(
-			`📎 <b>Preview/Download File</b>\n\n` +
-				`Usage: <code>/preview &lt;filepath&gt;</code>\n\n` +
-				`Examples:\n` +
-				`• <code>/preview output.txt</code> (relative to working dir)\n` +
-				`• <code>/preview /absolute/path/file.pdf</code>\n` +
-				`• <code>/preview ~/Documents/report.csv</code>`,
-			{ parse_mode: "HTML" },
-		);
-		return;
-	}
-
-	const inputPath = (match[1] ?? "").trim();
+async function sendFile(
+	ctx: Context,
+	filePath: string,
+): Promise<string | null> {
 	// Resolve relative paths from current working directory
-	const resolvedPath = resolvePath(inputPath, session.workingDir);
+	const resolvedPath = resolvePath(filePath, session.workingDir);
 
 	// Validate path exists
 	if (!existsSync(resolvedPath)) {
-		await ctx.reply(`❌ File not found: <code>${resolvedPath}</code>`, {
-			parse_mode: "HTML",
-		});
-		return;
+		return `File not found: ${resolvedPath}`;
 	}
 
 	const stats = statSync(resolvedPath);
 	if (stats.isDirectory()) {
-		await ctx.reply(
-			`❌ Cannot preview directory: <code>${resolvedPath}</code>\n\nUse <code>/cd</code> to navigate.`,
-			{ parse_mode: "HTML" },
-		);
-		return;
+		return `Cannot send directory: ${resolvedPath}`;
 	}
 
 	// Check if path is allowed
 	if (!isPathAllowed(resolvedPath)) {
-		await ctx.reply(
-			`❌ Access denied: <code>${resolvedPath}</code>\n\nPath must be in allowed directories.`,
-			{ parse_mode: "HTML" },
-		);
-		return;
+		return `Access denied: ${resolvedPath}`;
 	}
 
 	// Check file size (Telegram limit is 50MB for bots)
 	const MAX_FILE_SIZE = 50 * 1024 * 1024;
 	if (stats.size > MAX_FILE_SIZE) {
 		const sizeMB = (stats.size / (1024 * 1024)).toFixed(1);
-		await ctx.reply(
-			`❌ File too large: <code>${resolvedPath}</code>\n\nSize: ${sizeMB}MB (max 50MB)`,
-			{ parse_mode: "HTML" },
-		);
-		return;
+		return `File too large: ${resolvedPath} (${sizeMB}MB, max 50MB)`;
 	}
 
 	// Send the file
 	try {
 		const filename = resolvedPath.split("/").pop() || "file";
 		await ctx.replyWithDocument(new InputFile(resolvedPath, filename));
+		return null;
 	} catch (error) {
 		const errMsg = error instanceof Error ? error.message : String(error);
-		await ctx.reply(`❌ Failed to send file: ${errMsg}`);
+		return `Failed to send: ${errMsg}`;
+	}
+}
+
+/**
+ * /file - Send a file to the user.
+ * Without arguments: auto-detect file paths from last bot response.
+ */
+export async function handleFile(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized.");
+		return;
+	}
+
+	// Get the path argument from command
+	const text = ctx.message?.text || "";
+	const match = text.match(/^\/file\s+(.+)$/);
+
+	// If no argument, try to auto-detect from last bot response
+	if (!match) {
+		if (!session.lastBotResponse) {
+			await ctx.reply(
+				`📎 <b>Download File</b>\n\n` +
+					`Usage: <code>/file &lt;filepath&gt;</code>\n` +
+					`Or just <code>/file</code> to send files from the last response.\n\n` +
+					`No recent response to extract files from.`,
+				{ parse_mode: "HTML" },
+			);
+			return;
+		}
+
+		// Extract paths from <code> tags (response is HTML)
+		const codeMatches = session.lastBotResponse.matchAll(
+			/<code>([^<]+)<\/code>/g,
+		);
+		const candidates: string[] = [];
+		for (const m of codeMatches) {
+			const content = m[1]?.trim();
+			// Must have file extension (contains . followed by letters)
+			if (content && /\.[a-zA-Z0-9]+$/.test(content)) {
+				candidates.push(content);
+			}
+		}
+
+		// Deduplicate
+		const detected = [...new Set(candidates)];
+
+		if (detected.length === 0) {
+			await ctx.reply(
+				`📎 No file paths found in <code>&lt;code&gt;</code> tags.\n\n` +
+					`Usage: <code>/file &lt;filepath&gt;</code>`,
+				{ parse_mode: "HTML" },
+			);
+			return;
+		}
+
+		// Send each detected file
+		const errors: string[] = [];
+		let sent = 0;
+		for (const filePath of detected) {
+			const error = await sendFile(ctx, filePath);
+			if (error) {
+				errors.push(`${filePath}: ${error}`);
+			} else {
+				sent++;
+			}
+		}
+
+		// Report any errors
+		if (errors.length > 0) {
+			await ctx.reply(`⚠️ Some files failed:\n${errors.join("\n")}`, {
+				parse_mode: "HTML",
+			});
+		}
+
+		if (sent === 0 && errors.length > 0) {
+			// All failed, already reported above
+		} else if (sent > 0) {
+			// Success message optional, files speak for themselves
+		}
+
+		return;
+	}
+
+	// Explicit path provided
+	const inputPath = (match[1] ?? "").trim();
+	const error = await sendFile(ctx, inputPath);
+	if (error) {
+		await ctx.reply(`❌ ${error}`, { parse_mode: "HTML" });
 	}
 }
 

package/src/handlers/index.ts

@@ -6,14 +6,21 @@ export { handleCallback } from "./callback";
 export {
 	handleBookmarks,
 	handleCd,
+	handleCompact,
+	handleCost,
+	handleFile,
+	handleModel,
 	handleNew,
-	handlePreview,
+	handlePlan,
 	handleRestart,
 	handleResume,
 	handleRetry,
+	handleSkill,
 	handleStart,
 	handleStatus,
 	handleStop,
+	handleThink,
+	handleUndo,
 } from "./commands";
 export { handleDocument } from "./document";
 export { handlePhoto } from "./photo";

package/src/index.ts

@@ -17,17 +17,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";
 
@@ -60,12 +67,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 ==============