@grinev/opencode-telegram-bot 0.10.0 → 0.11.0

package/README.md

@@ -11,9 +11,9 @@ Run AI coding tasks, monitor progress, switch models, and manage sessions from y
 
 No open ports, no exposed APIs. The bot communicates with your local OpenCode server and the Telegram Bot API only.
 
-Languages: English (`en`), Deutsch (`de`), Español (`es`), Русский (`ru`), 简体中文 (`zh`)
+Platforms: macOS, Windows, Linux
 
-Quick start: `npx @grinev/opencode-telegram-bot`
+Languages: English (`en`), Deutsch (`de`), Español (`es`), Русский (`ru`), 简体中文 (`zh`)
 
 <p align="center">
   <img src="assets/screencast.gif" width="45%" alt="OpenCode Telegram Bot screencast" />
@@ -26,11 +26,12 @@ Quick start: `npx @grinev/opencode-telegram-bot`
 - **Live status** — pinned message with current project, model, context usage, and changed files list, updated in real time
 - **Model switching** — pick models from OpenCode favorites and recent history directly in the chat (favorites are shown first)
 - **Agent modes** — switch between Plan and Build modes on the fly
+- **Custom Commands** — run OpenCode custom commands (and built-ins like `init`/`review`) from an inline menu with confirmation
 - **Interactive Q&A** — answer agent questions and approve permissions via inline buttons
 - **Voice prompts** — send voice/audio messages, transcribe them via a Whisper-compatible API, then forward recognized text to OpenCode
+- **File attachments** — send images, PDF documents, and any text-based files to OpenCode (code, logs, configs etc.)
 - **Context control** — compact context when it gets too large, right from the chat
 - **Input flow control** — when an interactive flow is active, the bot accepts only relevant input to keep context consistent and avoid accidental actions
-- **Configurable reply formatting** — assistant replies use Telegram MarkdownV2 by default, with optional raw mode (`MESSAGE_FORMAT_MODE=markdown|raw`)
 - **Security** — strict user ID whitelist; no one else can access your bot, even if they find it
 - **Localization** — UI localization is supported for multiple languages (`BOT_LOCALE`)
 
@@ -68,6 +69,8 @@ The fastest way — run directly with `npx`:
 npx @grinev/opencode-telegram-bot
 ```
 
+> Quick start is for npm usage. You do not need to clone this repository. If you run this command from the source directory (repository root), it may fail with `opencode-telegram: not found`. To run from sources, use the [Development](#development) section.
+
 On first launch, an interactive wizard will guide you through the configuration — it asks for interface language first, then your bot token, user ID, and OpenCode API URL. After that, you're ready to go. Open your bot in Telegram and start sending tasks.
 
 #### Alternative: Global Install
@@ -85,11 +88,11 @@ opencode-telegram config
 
 ## Supported Platforms
 
-| Platform | Status                                                                                                                               |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| macOS    | Fully supported                                                                                                                      |
-| Windows  | Fully supported                                                                                                                      |
-| Linux    | Experimental — should work, but has not been extensively tested. You may need additional steps such as granting execute permissions. |
+| Platform | Status                                       |
+| -------- | -------------------------------------------- |
+| macOS    | Fully supported                              |
+| Windows  | Fully supported                              |
+| Linux    | Fully supported (tested on Ubuntu 24.04 LTS) |
 
 ## Bot Commands
 
@@ -101,6 +104,7 @@ opencode-telegram config
 | `/sessions`       | Browse and switch between recent sessions               |
 | `/projects`       | Switch between OpenCode projects                        |
 | `/rename`         | Rename the current session                              |
+| `/commands`       | Browse and run custom commands                          |
 | `/opencode_start` | Start the OpenCode server remotely                      |
 | `/opencode_stop`  | Stop the OpenCode server remotely                       |
 | `/help`           | Show available commands                                 |
@@ -137,7 +141,7 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `OPENCODE_MODEL_ID`             | Default model ID                                                                                             |   Yes    | `big-pickle`             |
 | `BOT_LOCALE`                    | Bot UI language (supported locale code, e.g. `en`, `de`, `es`, `ru`, `zh`)                                   |    No    | `en`                     |
 | `SESSIONS_LIST_LIMIT`           | Sessions per page in `/sessions`                                                                             |    No    | `10`                     |
-| `PROJECTS_LIST_LIMIT`           | Max projects shown in `/projects`                                                                            |    No    | `10`                     |
+| `PROJECTS_LIST_LIMIT`           | Projects per page in `/projects`                                                                             |    No    | `10`                     |
 | `SERVICE_MESSAGES_INTERVAL_SEC` | Service messages interval (thinking + tool calls); keep `>=2` to avoid Telegram rate limits, `0` = immediate |    No    | `5`                      |
 | `HIDE_THINKING_MESSAGES`        | Hide `💭 Thinking...` service messages                                                                       |    No    | `false`                  |
 | `HIDE_TOOL_CALL_MESSAGES`       | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.)                                         |    No    | `false`                  |
@@ -250,6 +254,10 @@ npm run dev
 
 Please follow commit and release note conventions in [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Community
+
+Have questions, want to share your experience using the bot, or have an idea for a feature? Join the conversation in [GitHub Discussions](https://github.com/grinev/opencode-telegram-bot/discussions).
+
 ## License
 
 [MIT](LICENSE) © Ruslan Grinev

package/dist/agent/manager.js

@@ -8,15 +8,9 @@ import { logger } from "../utils/logger.js";
  * @returns Array of available agents (filtered by mode and hidden flag)
  */
 export async function getAvailableAgents() {
-    const project = getCurrentProject();
-    if (!project) {
-        logger.warn("[AgentManager] Cannot get agents: no project selected");
-        return [];
-    }
     try {
-        const { data: agents, error } = await opencodeClient.app.agents({
-            directory: project.worktree,
-        });
+        const project = getCurrentProject();
+        const { data: agents, error } = await opencodeClient.app.agents(project ? { directory: project.worktree } : undefined);
         if (error) {
             logger.error("[AgentManager] Failed to fetch agents:", error);
             return [];
@@ -34,9 +28,11 @@ export async function getAvailableAgents() {
         return [];
     }
 }
+const DEFAULT_AGENT = "build";
 /**
- * Get current agent from last session message or settings
- * @returns Current agent name or undefined
+ * Get current agent from last session message or settings.
+ * Falls back to "build" if nothing is stored.
+ * @returns Current agent name
  */
 export async function fetchCurrentAgent() {
     const storedAgent = getCurrentAgent();
@@ -44,7 +40,7 @@ export async function fetchCurrentAgent() {
     const project = getCurrentProject();
     if (!session || !project) {
         // No active session, return stored agent from settings
-        return storedAgent;
+        return storedAgent ?? DEFAULT_AGENT;
     }
     try {
         const { data: messages, error } = await opencodeClient.session.messages({
@@ -54,7 +50,7 @@ export async function fetchCurrentAgent() {
         });
         if (error || !messages || messages.length === 0) {
             logger.debug("[AgentManager] No messages found, using stored agent");
-            return storedAgent;
+            return storedAgent ?? DEFAULT_AGENT;
         }
         const lastAgent = messages[0].info.agent;
         logger.debug(`[AgentManager] Current agent from session: ${lastAgent}`);
@@ -68,11 +64,11 @@ export async function fetchCurrentAgent() {
         if (lastAgent && lastAgent !== storedAgent) {
             setCurrentAgent(lastAgent);
         }
-        return lastAgent || storedAgent;
+        return lastAgent || storedAgent || DEFAULT_AGENT;
     }
     catch (err) {
         logger.error("[AgentManager] Error fetching current agent:", err);
-        return storedAgent;
+        return storedAgent ?? DEFAULT_AGENT;
     }
 }
 /**

package/dist/bot/commands/commands.js

@@ -0,0 +1,379 @@
+import { InlineKeyboard } from "grammy";
+import { opencodeClient } from "../../opencode/client.js";
+import { getCurrentProject } from "../../settings/manager.js";
+import { clearSession, getCurrentSession, setCurrentSession, } from "../../session/manager.js";
+import { ingestSessionInfoForCache } from "../../session/cache-manager.js";
+import { interactionManager } from "../../interaction/manager.js";
+import { summaryAggregator } from "../../summary/aggregator.js";
+import { getStoredAgent } from "../../agent/manager.js";
+import { getStoredModel } from "../../model/manager.js";
+import { safeBackgroundTask } from "../../utils/safe-background-task.js";
+import { logger } from "../../utils/logger.js";
+import { t } from "../../i18n/index.js";
+const COMMANDS_CALLBACK_PREFIX = "commands:";
+const COMMANDS_CALLBACK_SELECT_PREFIX = `${COMMANDS_CALLBACK_PREFIX}select:`;
+const COMMANDS_CALLBACK_CANCEL = `${COMMANDS_CALLBACK_PREFIX}cancel`;
+const COMMANDS_CALLBACK_EXECUTE = `${COMMANDS_CALLBACK_PREFIX}execute`;
+const MAX_INLINE_BUTTON_LABEL_LENGTH = 64;
+function formatExecutingCommandMessage(commandName, args) {
+    const commandText = `／${commandName}`;
+    const argsSuffix = args ? ` ${args}` : "";
+    return `${t("commands.executing_prefix")}\n${commandText}${argsSuffix}`;
+}
+function normalizeDirectoryForCommandApi(directory) {
+    return directory.replace(/\\/g, "/");
+}
+function getCallbackMessageId(ctx) {
+    const message = ctx.callbackQuery?.message;
+    if (!message || !("message_id" in message)) {
+        return null;
+    }
+    const messageId = message.message_id;
+    return typeof messageId === "number" ? messageId : null;
+}
+function formatCommandButtonLabel(command) {
+    const description = command.description?.trim() || t("commands.no_description");
+    const rawLabel = `/${command.name} - ${description}`;
+    if (rawLabel.length <= MAX_INLINE_BUTTON_LABEL_LENGTH) {
+        return rawLabel;
+    }
+    return `${rawLabel.slice(0, MAX_INLINE_BUTTON_LABEL_LENGTH - 3)}...`;
+}
+function buildCommandsListKeyboard(commands) {
+    const keyboard = new InlineKeyboard();
+    commands.forEach((command, index) => {
+        keyboard
+            .text(formatCommandButtonLabel(command), `${COMMANDS_CALLBACK_SELECT_PREFIX}${index}`)
+            .row();
+    });
+    keyboard.text(t("commands.button.cancel"), COMMANDS_CALLBACK_CANCEL);
+    return keyboard;
+}
+function buildCommandsConfirmKeyboard() {
+    return new InlineKeyboard()
+        .text(t("commands.button.execute"), COMMANDS_CALLBACK_EXECUTE)
+        .text(t("commands.button.cancel"), COMMANDS_CALLBACK_CANCEL);
+}
+function parseCommandItems(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const commands = [];
+    for (const item of value) {
+        if (!item || typeof item !== "object") {
+            return null;
+        }
+        const commandName = item.name;
+        if (typeof commandName !== "string" || !commandName.trim()) {
+            return null;
+        }
+        const description = item.description;
+        commands.push({
+            name: commandName,
+            description: typeof description === "string" ? description : undefined,
+        });
+    }
+    return commands;
+}
+function parseCommandsMetadata(state) {
+    if (!state || state.kind !== "custom") {
+        return null;
+    }
+    const flow = state.metadata.flow;
+    const stage = state.metadata.stage;
+    const messageId = state.metadata.messageId;
+    const projectDirectory = state.metadata.projectDirectory;
+    if (flow !== "commands" ||
+        typeof messageId !== "number" ||
+        typeof projectDirectory !== "string") {
+        return null;
+    }
+    if (stage === "list") {
+        const commands = parseCommandItems(state.metadata.commands);
+        if (!commands) {
+            return null;
+        }
+        return {
+            flow,
+            stage,
+            messageId,
+            projectDirectory,
+            commands,
+        };
+    }
+    if (stage === "confirm") {
+        const commandName = state.metadata.commandName;
+        if (typeof commandName !== "string" || !commandName.trim()) {
+            return null;
+        }
+        return {
+            flow,
+            stage,
+            messageId,
+            projectDirectory,
+            commandName,
+        };
+    }
+    return null;
+}
+function clearCommandsInteraction(reason) {
+    const metadata = parseCommandsMetadata(interactionManager.getSnapshot());
+    if (metadata) {
+        interactionManager.clear(reason);
+    }
+}
+async function getCommandList(projectDirectory) {
+    const { data, error } = await opencodeClient.command.list({
+        directory: normalizeDirectoryForCommandApi(projectDirectory),
+    });
+    if (error || !data) {
+        throw error || new Error("No command data received");
+    }
+    return data
+        .filter((command) => typeof command.name === "string" && command.name.trim().length > 0)
+        .map((command) => ({
+        name: command.name,
+        description: command.description,
+    }));
+}
+function parseSelectIndex(data) {
+    if (!data.startsWith(COMMANDS_CALLBACK_SELECT_PREFIX)) {
+        return null;
+    }
+    const rawIndex = data.slice(COMMANDS_CALLBACK_SELECT_PREFIX.length);
+    const index = Number(rawIndex);
+    if (!Number.isInteger(index) || index < 0) {
+        return null;
+    }
+    return index;
+}
+async function isSessionBusy(sessionId, directory) {
+    try {
+        const { data, error } = await opencodeClient.session.status({ directory });
+        if (error || !data) {
+            logger.warn("[Commands] Failed to check session status before command:", error);
+            return false;
+        }
+        const sessionStatus = data[sessionId];
+        if (!sessionStatus) {
+            return false;
+        }
+        return sessionStatus.type === "busy";
+    }
+    catch (err) {
+        logger.warn("[Commands] Error checking session status before command:", err);
+        return false;
+    }
+}
+async function ensureSessionForProject(ctx, projectDirectory) {
+    let currentSession = getCurrentSession();
+    if (currentSession && currentSession.directory !== projectDirectory) {
+        logger.warn(`[Commands] Session/project mismatch detected. sessionDirectory=${currentSession.directory}, projectDirectory=${projectDirectory}. Resetting session context.`);
+        clearSession();
+        summaryAggregator.clear();
+        await ctx.reply(t("bot.session_reset_project_mismatch"));
+        currentSession = null;
+    }
+    if (currentSession) {
+        return currentSession;
+    }
+    await ctx.reply(t("bot.creating_session"));
+    const { data: session, error } = await opencodeClient.session.create({
+        directory: projectDirectory,
+    });
+    if (error || !session) {
+        await ctx.reply(t("bot.create_session_error"));
+        return null;
+    }
+    const sessionInfo = {
+        id: session.id,
+        title: session.title,
+        directory: projectDirectory,
+    };
+    setCurrentSession(sessionInfo);
+    await ingestSessionInfoForCache(session);
+    await ctx.reply(t("bot.session_created", { title: session.title }));
+    return sessionInfo;
+}
+async function executeCommand(ctx, deps, params) {
+    if (!ctx.chat) {
+        return;
+    }
+    const args = params.argumentsText.trim();
+    await ctx.reply(formatExecutingCommandMessage(params.commandName, args));
+    const session = await ensureSessionForProject(ctx, params.projectDirectory);
+    if (!session) {
+        return;
+    }
+    await deps.ensureEventSubscription(session.directory);
+    summaryAggregator.setSession(session.id);
+    summaryAggregator.setBotAndChatId(deps.bot, ctx.chat.id);
+    const sessionIsBusy = await isSessionBusy(session.id, session.directory);
+    if (sessionIsBusy) {
+        await ctx.reply(t("bot.session_busy"));
+        return;
+    }
+    const currentAgent = getStoredAgent();
+    const storedModel = getStoredModel();
+    const model = storedModel.providerID && storedModel.modelID
+        ? `${storedModel.providerID}/${storedModel.modelID}`
+        : undefined;
+    safeBackgroundTask({
+        taskName: "session.command",
+        task: () => opencodeClient.session.command({
+            sessionID: session.id,
+            directory: session.directory,
+            command: params.commandName,
+            arguments: args,
+            agent: currentAgent,
+            model,
+            variant: storedModel.variant,
+        }),
+        onSuccess: ({ error }) => {
+            if (error) {
+                logger.error("[Commands] OpenCode API returned an error for session.command", {
+                    sessionId: session.id,
+                    command: params.commandName,
+                    args,
+                });
+                logger.error("[Commands] session.command error details:", error);
+                void ctx.api.sendMessage(ctx.chat.id, t("commands.execute_error")).catch(() => { });
+                return;
+            }
+            logger.info(`[Commands] session.command completed: session=${session.id}, command=/${params.commandName}`);
+        },
+        onError: (error) => {
+            logger.error("[Commands] session.command background task failed", {
+                sessionId: session.id,
+                command: params.commandName,
+                args,
+            });
+            logger.error("[Commands] session.command background failure details:", error);
+            void ctx.api.sendMessage(ctx.chat.id, t("commands.execute_error")).catch(() => { });
+        },
+    });
+}
+export async function commandsCommand(ctx) {
+    try {
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            await ctx.reply(t("bot.project_not_selected"));
+            return;
+        }
+        const commands = await getCommandList(currentProject.worktree);
+        if (commands.length === 0) {
+            await ctx.reply(t("commands.empty"));
+            return;
+        }
+        const keyboard = buildCommandsListKeyboard(commands);
+        const message = await ctx.reply(t("commands.select"), {
+            reply_markup: keyboard,
+        });
+        interactionManager.start({
+            kind: "custom",
+            expectedInput: "callback",
+            metadata: {
+                flow: "commands",
+                stage: "list",
+                messageId: message.message_id,
+                projectDirectory: currentProject.worktree,
+                commands,
+            },
+        });
+    }
+    catch (error) {
+        logger.error("[Commands] Error fetching commands list:", error);
+        await ctx.reply(t("commands.fetch_error"));
+    }
+}
+export async function handleCommandsCallback(ctx, deps) {
+    const data = ctx.callbackQuery?.data;
+    if (!data || !data.startsWith(COMMANDS_CALLBACK_PREFIX)) {
+        return false;
+    }
+    const metadata = parseCommandsMetadata(interactionManager.getSnapshot());
+    const callbackMessageId = getCallbackMessageId(ctx);
+    if (!metadata || callbackMessageId === null || metadata.messageId !== callbackMessageId) {
+        await ctx.answerCallbackQuery({ text: t("commands.inactive_callback"), show_alert: true });
+        return true;
+    }
+    try {
+        if (data === COMMANDS_CALLBACK_CANCEL) {
+            clearCommandsInteraction("commands_cancelled");
+            await ctx.answerCallbackQuery({ text: t("commands.cancelled_callback") });
+            await ctx.deleteMessage().catch(() => { });
+            return true;
+        }
+        if (data === COMMANDS_CALLBACK_EXECUTE) {
+            if (metadata.stage !== "confirm") {
+                await ctx.answerCallbackQuery({ text: t("commands.inactive_callback"), show_alert: true });
+                return true;
+            }
+            clearCommandsInteraction("commands_execute_clicked");
+            await ctx.answerCallbackQuery({ text: t("commands.execute_callback") });
+            await ctx.deleteMessage().catch(() => { });
+            await executeCommand(ctx, deps, {
+                projectDirectory: metadata.projectDirectory,
+                commandName: metadata.commandName,
+                argumentsText: "",
+            });
+            return true;
+        }
+        const commandIndex = parseSelectIndex(data);
+        if (commandIndex === null || metadata.stage !== "list") {
+            await ctx.answerCallbackQuery({ text: t("callback.processing_error"), show_alert: true });
+            return true;
+        }
+        const selectedCommand = metadata.commands[commandIndex];
+        if (!selectedCommand) {
+            await ctx.answerCallbackQuery({ text: t("commands.inactive_callback"), show_alert: true });
+            return true;
+        }
+        await ctx.answerCallbackQuery();
+        await ctx.editMessageText(t("commands.confirm", { command: `/${selectedCommand.name}` }), {
+            reply_markup: buildCommandsConfirmKeyboard(),
+        });
+        interactionManager.transition({
+            expectedInput: "mixed",
+            metadata: {
+                flow: "commands",
+                stage: "confirm",
+                messageId: metadata.messageId,
+                projectDirectory: metadata.projectDirectory,
+                commandName: selectedCommand.name,
+            },
+        });
+        return true;
+    }
+    catch (error) {
+        logger.error("[Commands] Error handling command callback:", error);
+        clearCommandsInteraction("commands_callback_error");
+        await ctx.answerCallbackQuery({ text: t("callback.processing_error") }).catch(() => { });
+        return true;
+    }
+}
+export async function handleCommandTextArguments(ctx, deps) {
+    const text = ctx.message?.text;
+    if (!text || text.startsWith("/")) {
+        return false;
+    }
+    const metadata = parseCommandsMetadata(interactionManager.getSnapshot());
+    if (!metadata || metadata.stage !== "confirm") {
+        return false;
+    }
+    const argumentsText = text.trim();
+    if (!argumentsText) {
+        await ctx.reply(t("commands.arguments_empty"));
+        return true;
+    }
+    clearCommandsInteraction("commands_arguments_submitted");
+    if (ctx.chat) {
+        await ctx.api.deleteMessage(ctx.chat.id, metadata.messageId).catch(() => { });
+    }
+    await executeCommand(ctx, deps, {
+        projectDirectory: metadata.projectDirectory,
+        commandName: metadata.commandName,
+        argumentsText,
+    });
+    return true;
+}

package/dist/bot/commands/definitions.js

@@ -10,6 +10,7 @@ const COMMAND_DEFINITIONS = [
     { command: "sessions", descriptionKey: "cmd.description.sessions" },
     { command: "projects", descriptionKey: "cmd.description.projects" },
     { command: "rename", descriptionKey: "cmd.description.rename" },
+    { command: "commands", descriptionKey: "cmd.description.commands" },
     { command: "opencode_start", descriptionKey: "cmd.description.opencode_start" },
     { command: "opencode_stop", descriptionKey: "cmd.description.opencode_stop" },
     { command: "help", descriptionKey: "cmd.description.help" },

package/dist/bot/commands/projects.js

@@ -11,11 +11,12 @@ import { getStoredModel } from "../../model/manager.js";
 import { formatVariantForButton } from "../../variant/manager.js";
 import { clearAllInteractionState } from "../../interaction/cleanup.js";
 import { createMainKeyboard } from "../utils/keyboard.js";
-import { ensureActiveInlineMenu, replyWithInlineMenu } from "../handlers/inline-menu.js";
+import { appendInlineMenuCancelButton, ensureActiveInlineMenu, replyWithInlineMenu, } from "../handlers/inline-menu.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 import { config } from "../../config.js";
 const MAX_INLINE_BUTTON_LABEL_LENGTH = 64;
+const PROJECT_PAGE_CALLBACK_PREFIX = "projects:page:";
 function formatProjectButtonLabel(label, isActive) {
     const prefix = isActive ? "✅ " : "";
     const availableLength = MAX_INLINE_BUTTON_LABEL_LENGTH - prefix.length;
@@ -36,29 +37,84 @@ export function buildProjectButtonLabel(index, worktree) {
     const folderName = getProjectFolderName(worktree);
     return `${index + 1}. ${folderName} [${worktree}]`;
 }
+export function parseProjectPageCallback(data) {
+    if (!data.startsWith(PROJECT_PAGE_CALLBACK_PREFIX)) {
+        return null;
+    }
+    const rawPage = data.slice(PROJECT_PAGE_CALLBACK_PREFIX.length);
+    if (!/^\d+$/.test(rawPage)) {
+        return null;
+    }
+    return Number.parseInt(rawPage, 10);
+}
+export function calculateProjectsPaginationRange(totalProjects, page, pageSize) {
+    const safePageSize = Math.max(1, pageSize);
+    const totalPages = Math.max(1, Math.ceil(totalProjects / safePageSize));
+    const normalizedPage = Math.min(Math.max(0, page), totalPages - 1);
+    const startIndex = normalizedPage * safePageSize;
+    const endIndex = Math.min(startIndex + safePageSize, totalProjects);
+    return {
+        page: normalizedPage,
+        totalPages,
+        startIndex,
+        endIndex,
+    };
+}
+function buildProjectsMenuText(currentProjectName, page, totalPages) {
+    const baseText = currentProjectName
+        ? t("projects.select_with_current", {
+            project: currentProjectName,
+        })
+        : t("projects.select");
+    if (totalPages <= 1) {
+        return baseText;
+    }
+    return `${baseText}\n\n${t("projects.page_indicator", {
+        current: String(page + 1),
+        total: String(totalPages),
+    })}`;
+}
+function buildProjectsKeyboard(projects, page) {
+    const keyboard = new InlineKeyboard();
+    const currentProject = getCurrentProject();
+    const pageSize = config.bot.projectsListLimit;
+    const { page: normalizedPage, totalPages, startIndex, endIndex, } = calculateProjectsPaginationRange(projects.length, page, pageSize);
+    projects.slice(startIndex, endIndex).forEach((project, index) => {
+        const isActive = currentProject &&
+            (project.id === currentProject.id || project.worktree === currentProject.worktree);
+        const label = buildProjectButtonLabel(startIndex + index, project.worktree);
+        const labelWithCheck = formatProjectButtonLabel(label, Boolean(isActive));
+        keyboard.text(labelWithCheck, `project:${project.id}`).row();
+    });
+    if (totalPages > 1) {
+        if (normalizedPage > 0) {
+            keyboard.text(t("projects.prev_page"), `${PROJECT_PAGE_CALLBACK_PREFIX}${normalizedPage - 1}`);
+        }
+        if (normalizedPage < totalPages - 1) {
+            keyboard.text(t("projects.next_page"), `${PROJECT_PAGE_CALLBACK_PREFIX}${normalizedPage + 1}`);
+        }
+    }
+    return keyboard;
+}
+function buildProjectsMenuView(projects, page) {
+    const currentProject = getCurrentProject();
+    const pageSize = config.bot.projectsListLimit;
+    const { page: normalizedPage, totalPages } = calculateProjectsPaginationRange(projects.length, page, pageSize);
+    const currentProjectName = currentProject?.name || currentProject?.worktree || null;
+    return {
+        text: buildProjectsMenuText(currentProjectName, normalizedPage, totalPages),
+        keyboard: buildProjectsKeyboard(projects, normalizedPage),
+    };
+}
 export async function projectsCommand(ctx) {
     try {
         await syncSessionDirectoryCache();
         const projects = await getProjects();
-        const projectsToShow = projects.slice(0, config.bot.projectsListLimit);
-        if (projectsToShow.length === 0) {
+        if (projects.length === 0) {
             await ctx.reply(t("projects.empty"));
             return;
         }
-        const keyboard = new InlineKeyboard();
-        const currentProject = getCurrentProject();
-        projectsToShow.forEach((project, index) => {
-            const isActive = currentProject &&
-                (project.id === currentProject.id || project.worktree === currentProject.worktree);
-            const label = buildProjectButtonLabel(index, project.worktree);
-            const labelWithCheck = formatProjectButtonLabel(label, Boolean(isActive));
-            keyboard.text(labelWithCheck, `project:${project.id}`).row();
-        });
-        const text = currentProject
-            ? t("projects.select_with_current", {
-                project: currentProject.name || currentProject.worktree,
-            })
-            : t("projects.select");
+        const { text, keyboard } = buildProjectsMenuView(projects, 0);
         await replyWithInlineMenu(ctx, {
             menuKind: "project",
             text,
@@ -72,7 +128,35 @@ export async function projectsCommand(ctx) {
 }
 export async function handleProjectSelect(ctx) {
     const callbackQuery = ctx.callbackQuery;
-    if (!callbackQuery?.data || !callbackQuery.data.startsWith("project:")) {
+    if (!callbackQuery?.data) {
+        return false;
+    }
+    const page = parseProjectPageCallback(callbackQuery.data);
+    if (page !== null) {
+        const isActiveMenu = await ensureActiveInlineMenu(ctx, "project");
+        if (!isActiveMenu) {
+            return true;
+        }
+        try {
+            const projects = await getProjects();
+            if (projects.length === 0) {
+                await ctx.answerCallbackQuery();
+                await ctx.reply(t("projects.empty"));
+                return true;
+            }
+            const { text, keyboard } = buildProjectsMenuView(projects, page);
+            await ctx.answerCallbackQuery();
+            await ctx.editMessageText(text, {
+                reply_markup: appendInlineMenuCancelButton(keyboard, "project"),
+            });
+        }
+        catch (error) {
+            logger.error("[Bot] Error switching projects page:", error);
+            await ctx.answerCallbackQuery({ text: t("projects.page_load_error") });
+        }
+        return true;
+    }
+    if (!callbackQuery.data.startsWith("project:")) {
         return false;
     }
     const projectId = callbackQuery.data.replace("project:", "");