@deadragdoll/tellymcp 0.0.9 → 0.0.11

package/scripts/postinstall.js

@@ -3,61 +3,36 @@
 const { spawnSync } = require("node:child_process");
 const pc = require("picocolors");
 
-function getTmuxStatus() {
-  const result = spawnSync("tmux", ["-V"], {
+function hasCodex() {
+  const result = spawnSync("codex", ["--version"], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],
   });
-
-  if (result.status === 0) {
-    return {
-      found: true,
-      version: (result.stdout || "tmux").trim(),
-    };
-  }
-
-  return { found: false };
-}
-
-function getInstallHints() {
-  if (process.platform === "darwin") {
-    return ["brew install tmux"];
-  }
-
-  return [
-    "Ubuntu/Debian: sudo apt install tmux",
-    "Fedora/RHEL:   sudo dnf install tmux",
-    "Arch:          sudo pacman -S tmux",
-  ];
+  return result.status === 0;
 }
 
 function line(value = "") {
   process.stdout.write(`${value}\n`);
 }
 
-const tmux = getTmuxStatus();
-
 line();
 line(`${pc.bold(pc.cyan("TellyMCP"))} ${pc.dim("installed")}`);
 line();
 
-if (tmux.found) {
-  line(`${pc.green("OK")} tmux detected: ${tmux.version}`);
-  line("Live view and session nudges should work on this machine.");
-} else {
-  line(`${pc.yellow("WARN")} tmux was not found on this system.`);
-  line("TellyMCP can still run, but Live view and nudges will be limited.");
-  line("Install tmux, for example:");
-  for (const hint of getInstallHints()) {
-    line(`  ${hint}`);
-  }
-}
+line(`${pc.green("OK")} Built-in PTY terminal runtime is enabled.`);
 
 line();
 line(`${pc.yellow("INFO")} Browser tools need Playwright browser binaries.`);
 line("If you plan to use browser_* tools, run:");
 line(`  ${pc.bold("tellymcp browser install")}`);
 
+if (hasCodex()) {
+  line();
+  line(`${pc.yellow("INFO")} Codex CLI detected on this machine.`);
+  line("To sync or update the bundled Codex workflow plugin, run:");
+  line(`  ${pc.bold("tellymcp codex-plugin install")}`);
+}
+
 line();
 line(`Check your local setup: ${pc.bold("tellymcp doctor")}`);
 line(`General help: ${pc.bold("tellymcp help")}`);

package/STANDALONE-ru.md

@@ -1,274 +0,0 @@
-# TellyMCP Standalone Guide
-
-[English](STANDALONE.md) | [Русский](STANDALONE-ru.md)
-
-Это пошаговая инструкция для самого простого сценария TellyMCP:
-
-- одна машина
-- один Telegram-бот
-- без shared gateway
-- без Postgres
-- без RabbitMQ
-
-Именно с этого режима лучше начинать.
-
-## Что понадобится
-
-Перед установкой нужны:
-
-1. Node.js 24+
-2. `tmux`
-3. Redis
-4. Telegram bot token из BotFather
-5. опционально для `browser_*` tools: Playwright Chromium browser binaries
-
-Зачем это нужно:
-
-- Node.js запускает сервис
-- `tmux` нужен для Live View, `nudge` и полноценной интерактивной работы
-- Redis хранит состояние сессий, inbox, pairing и меню
-- Telegram bot token связывает сервис с Telegram
-
-## Шаг 1. Установить зависимости
-
-Пример для Ubuntu / Debian:
-
-```bash
-sudo apt-get update
-sudo apt-get install -y tmux redis-server
-node -v
-tmux -V
-redis-cli ping
-```
-
-Ожидаемый результат:
-
-- Node версии `24.x` или новее
-- `tmux -V` показывает версию
-- `redis-cli ping` возвращает `PONG`
-
-Если планируешь использовать browser automation tools, один раз выполни ещё:
-
-```bash
-tellymcp browser install
-```
-
-## Шаг 2. Создать Telegram-бота
-
-В Telegram:
-
-1. Открой BotFather
-2. Выполни `/newbot`
-3. Выбери имя бота
-4. Выбери username бота
-5. Сохрани токен
-
-Тебе понадобятся:
-
-- `TELEGRAM_BOT_TOKEN`
-- `TELEGRAM_BOT_USERNAME`
-
-## Шаг 3. Установить TellyMCP
-
-```bash
-npm install -g @deadragdoll/tellymcp
-```
-
-Проверка CLI:
-
-```bash
-tellymcp help
-```
-
-## Шаг 4. Запустить агента в tmux
-
-Это важный момент.
-
-Для полноценной работы агент лучше запускать внутри `tmux`, а не в обычной shell-сессии.
-
-Создать tmux-сессию:
-
-```bash
-tmux new -s backend
-```
-
-Хорошие имена:
-
-- `backend`
-- `frontend`
-- `review`
-- `ops`
-
-Почему имя tmux-сессии важно:
-
-- по нему проще различать агентов
-- оно улучшает диагностику
-- в Telegram и Live View проще понимать, какая сессия открыта
-
-Если нужно выйти:
-
-```bash
-tmux detach
-```
-
-И вернуться:
-
-```bash
-tmux attach -t backend
-```
-
-## Шаг 5. Создать standalone-конфиг
-
-В рабочей директории:
-
-```bash
-tellymcp init client
-```
-
-Команда создаст локальный `.env`.
-
-## Шаг 6. Заполнить `.env`
-
-Минимум:
-
-```env
-TELEGRAM_BOT_TOKEN=...
-TELEGRAM_BOT_USERNAME=@your_bot
-REDIS_HOST=127.0.0.1
-REDIS_PORT=6379
-REDIS_DB=1
-MCP_HTTP_HOST=127.0.0.1
-MCP_HTTP_PORT=8787
-MCP_HTTP_PATH=/mcp
-MCP_HTTP_BEARER_TOKEN=choose-a-secret-token
-DISTRIBUTED_MODE=client
-WEBAPP_ENABLED=true
-```
-
-Если tmux использует нестандартный socket:
-
-```env
-TMUX_SOCKET_PATH=/tmp/tmux-1000/default
-```
-
-## Шаг 7. Проверить конфиг
-
-```bash
-tellymcp doctor --env .env
-```
-
-В standalone `client` режиме он должен проверить:
-
-- `tmux`
-- `.env`
-- Redis
-- локальный MCP bind
-- Playwright Chromium, если browser tools включены
-
-## Шаг 8. Запустить сервис
-
-```bash
-tellymcp run --env .env
-```
-
-Обычный standalone MCP endpoint:
-
-- `http://127.0.0.1:8787/mcp`
-
-## Шаг 9. Подключить MCP к агенту
-
-Чтобы получить готовый snippet:
-
-```bash
-tellymcp mcp --help
-```
-
-Типичный локальный endpoint:
-
-- `http://127.0.0.1:8787/mcp`
-
-Если используешь bearer auth, агент должен подключаться с тем же токеном, что и в `.env`.
-
-## Шаг 10. Привязать агента к Telegram
-
-После подключения MCP можно просто написать агенту:
-
-- `привяжись к Telegram`
-- `подключись к Telegram`
-- `свяжи эту сессию с Telegram`
-- `создай код привязки к Telegram`
-
-Ожидаемый flow:
-
-1. агент вызывает `create_session_pair_code`
-2. отдаёт короткий код
-3. ты отправляешь боту `/start <code>` или `/link <code>`
-4. после успеха открываешь `/menu`
-
-Если агент работает внутри `tmux`, ему желательно передать:
-
-- `cwd`
-- имя tmux-сессии
-- tmux window/pane атрибуты
-
-Тогда `Live` и `nudge` заработают сразу.
-
-## Шаг 11. Что будет после pairing
-
-После привязки Telegram можно использовать для:
-
-- inbox
-- вопросов к человеку
-- local partner collaboration
-- переключения сессий
-- просмотра storage
-- Live View
-
-Агент сможет:
-
-- вызывать `ask_user_telegram`
-- читать несвязанные входящие сообщения
-- отправлять note и файлы
-- получать tmux `nudge`, когда появляется новая работа
-
-## Что работает без tmux
-
-TellyMCP можно запустить и без `tmux`, но это урезанный режим.
-
-Не будет:
-
-- Live View
-- tmux `nudge`
-- прямого управления из Telegram Mini App
-
-Такой режим стоит использовать только если тебя устраивает пассивная работа.
-
-## Troubleshooting
-
-Если `doctor` ругается:
-
-- проверь, что Redis запущен
-- проверь, что установлен `tmux`
-- проверь правильность bot token
-- проверь, что bearer token совпадает с MCP-конфигом агента
-
-Если pairing работает, а Live View нет:
-
-- убедись, что агент действительно запущен внутри `tmux`
-- убедись, что у tmux-сессии есть стабильное имя
-- при необходимости задай `TMUX_SOCKET_PATH`
-
-Если агент не может подключиться к MCP:
-
-- проверь, что `tellymcp run --env .env` действительно запущен
-- проверь endpoint `http://127.0.0.1:8787/mcp`
-- проверь bearer token
-
-## Следующий шаг
-
-Когда standalone уже работает, дальше можно переходить к:
-
-- `gateway`
-- или `both`
-
-Это нужно только если нужен `Collab` между машинами.

package/STANDALONE.md

@@ -1,274 +0,0 @@
-# TellyMCP Standalone Guide
-
-[English](STANDALONE.md) | [Русский](STANDALONE-ru.md)
-
-This guide explains the simplest TellyMCP setup:
-
-- one machine
-- one Telegram bot
-- no shared gateway
-- no Postgres
-- no RabbitMQ
-
-This is the best way to start.
-
-## What you need
-
-Before installation, make sure you have:
-
-1. Node.js 24+
-2. `tmux`
-3. Redis
-4. a Telegram bot token from BotFather
-5. optional for `browser_*` tools: Playwright Chromium browser binaries
-
-Why these matter:
-
-- Node.js runs the service
-- `tmux` enables Live View, nudges, and direct Telegram-side interaction
-- Redis stores session state, inbox, pairing state, and menu state
-- Telegram bot token connects your bot to Telegram
-
-## Step 1. Install prerequisites
-
-Ubuntu / Debian example:
-
-```bash
-sudo apt-get update
-sudo apt-get install -y tmux redis-server
-node -v
-tmux -V
-redis-cli ping
-```
-
-Expected:
-
-- Node version is `24.x` or newer
-- `tmux -V` prints a version
-- `redis-cli ping` returns `PONG`
-
-If you plan to use browser automation tools later, also run:
-
-```bash
-tellymcp browser install
-```
-
-## Step 2. Create a Telegram bot
-
-In Telegram:
-
-1. Open BotFather
-2. Run `/newbot`
-3. Choose a bot name
-4. Choose a bot username
-5. Save the token
-
-You will need:
-
-- `TELEGRAM_BOT_TOKEN`
-- `TELEGRAM_BOT_USERNAME`
-
-## Step 3. Install TellyMCP
-
-```bash
-npm install -g @deadragdoll/tellymcp
-```
-
-Check that the CLI works:
-
-```bash
-tellymcp help
-```
-
-## Step 4. Start a tmux session for the agent
-
-This part is important.
-
-Run the agent inside `tmux`, not in a plain shell, if you want the full experience.
-
-Create a session:
-
-```bash
-tmux new -s backend
-```
-
-Good session names:
-
-- `backend`
-- `frontend`
-- `review`
-- `ops`
-
-Why the session name matters:
-
-- it helps identify the agent in practice
-- it improves diagnostics
-- it makes Telegram and Live View easier to understand
-
-If you later detach:
-
-```bash
-tmux detach
-```
-
-and return:
-
-```bash
-tmux attach -t backend
-```
-
-## Step 5. Create the standalone config
-
-Inside the workspace where you want to run TellyMCP:
-
-```bash
-tellymcp init client
-```
-
-This creates a local `.env`.
-
-## Step 6. Fill `.env`
-
-At minimum, set:
-
-```env
-TELEGRAM_BOT_TOKEN=...
-TELEGRAM_BOT_USERNAME=@your_bot
-REDIS_HOST=127.0.0.1
-REDIS_PORT=6379
-REDIS_DB=1
-MCP_HTTP_HOST=127.0.0.1
-MCP_HTTP_PORT=8787
-MCP_HTTP_PATH=/mcp
-MCP_HTTP_BEARER_TOKEN=choose-a-secret-token
-DISTRIBUTED_MODE=client
-WEBAPP_ENABLED=true
-```
-
-If your tmux server uses a non-default socket:
-
-```env
-TMUX_SOCKET_PATH=/tmp/tmux-1000/default
-```
-
-## Step 7. Validate the setup
-
-```bash
-tellymcp doctor --env .env
-```
-
-In standalone `client` mode it should verify:
-
-- `tmux`
-- `.env`
-- Redis
-- local MCP bind
-- Playwright Chromium when browser tools are enabled
-
-## Step 8. Run the service
-
-```bash
-tellymcp run --env .env
-```
-
-Standalone MCP endpoint is normally:
-
-- `http://127.0.0.1:8787/mcp`
-
-## Step 9. Add MCP to your agent
-
-To get a ready-to-paste config snippet:
-
-```bash
-tellymcp mcp --help
-```
-
-Typical local MCP config target:
-
-- `http://127.0.0.1:8787/mcp`
-
-If you use bearer auth, configure your agent with the same token from `.env`.
-
-## Step 10. Pair the agent with Telegram
-
-Once MCP is connected, tell the agent something like:
-
-- `pair with Telegram`
-- `link to Telegram`
-- `connect this session to Telegram`
-- `create a Telegram pairing code`
-
-Expected flow:
-
-1. the agent calls `create_session_pair_code`
-2. it gives you a short code
-3. you send `/start <code>` or `/link <code>` to the bot
-4. after success, open `/menu`
-
-If the agent is running inside `tmux`, it should pass:
-
-- `cwd`
-- tmux session name
-- tmux window/pane attributes
-
-This lets Live View and tmux nudges work immediately.
-
-## Step 11. What you get after pairing
-
-After pairing, Telegram can be used for:
-
-- inbox messages
-- clarifying questions
-- local partner collaboration
-- session switching
-- storage inspection
-- Live View
-
-The agent can:
-
-- call `ask_user_telegram`
-- read unsolicited inbox messages
-- send notes and files
-- receive tmux nudges when new work arrives
-
-## What works without tmux
-
-TellyMCP can still run without `tmux`, but this is a reduced mode.
-
-You lose:
-
-- Live View
-- tmux nudges
-- direct Telegram Mini App controls
-
-Use this only if you accept a passive workflow.
-
-## Troubleshooting
-
-If `doctor` fails:
-
-- verify Redis is running
-- verify `tmux` is installed
-- verify the bot token is correct
-- verify your bearer token matches the MCP client config
-
-If pairing works but Live View does not:
-
-- make sure the agent is really inside `tmux`
-- make sure the tmux session has a stable name
-- if needed, set `TMUX_SOCKET_PATH`
-
-If the agent cannot connect to MCP:
-
-- confirm `tellymcp run --env .env` is running
-- confirm the endpoint is `http://127.0.0.1:8787/mcp`
-- confirm the bearer token matches
-
-## Next step
-
-After standalone is working, the next upgrade path is:
-
-- `gateway`
-- or `both`
-
-Use that only when you need cross-machine collaboration.

package/dist/services/features/telegram-mcp/inbox.service.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TELEGRAM_MCP_INBOX_SERVICE_NAME = void 0;
-const runtime_service_1 = require("./runtime.service");
-const inboxService_1 = require("./src/features/inbox/model/inboxService");
-exports.TELEGRAM_MCP_INBOX_SERVICE_NAME = "telegramMcp.inbox";
-const TelegramMcpInboxService = {
-    name: exports.TELEGRAM_MCP_INBOX_SERVICE_NAME,
-    dependencies: [runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME],
-    created() {
-        this.inboxService = null;
-    },
-    methods: {
-        getInboxService() {
-            if (!this.inboxService) {
-                throw new Error("telegram_mcp inbox service is not initialized yet");
-            }
-            return this.inboxService;
-        },
-    },
-    async started() {
-        await this.broker.waitForServices([runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME]);
-        const runtimeService = this.broker.getLocalService(runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME);
-        if (!runtimeService) {
-            throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
-        }
-        const runtime = runtimeService.getRuntime();
-        this.logger.info("Starting telegram_mcp inbox service");
-        this.inboxService = new inboxService_1.InboxService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver);
-        this.logger.info("telegram_mcp inbox service is ready");
-    },
-};
-exports.default = TelegramMcpInboxService;

package/dist/services/features/telegram-mcp/pair.service.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TELEGRAM_MCP_PAIR_SERVICE_NAME = void 0;
-const runtime_service_1 = require("./runtime.service");
-const generatePairCode_1 = require("./src/features/pair-session/model/generatePairCode");
-exports.TELEGRAM_MCP_PAIR_SERVICE_NAME = "telegramMcp.pair";
-const TelegramMcpPairService = {
-    name: exports.TELEGRAM_MCP_PAIR_SERVICE_NAME,
-    dependencies: [runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME],
-    created() {
-        this.pairSessionService = null;
-    },
-    methods: {
-        getPairSessionService() {
-            if (!this.pairSessionService) {
-                throw new Error("telegram_mcp pair service is not initialized yet");
-            }
-            return this.pairSessionService;
-        },
-    },
-    async started() {
-        await this.broker.waitForServices([runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME]);
-        const runtimeService = this.broker.getLocalService(runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME);
-        if (!runtimeService) {
-            throw new Error(`Local Moleculer service '${runtime_service_1.TELEGRAM_MCP_RUNTIME_SERVICE_NAME}' is unavailable`);
-        }
-        const runtime = runtimeService.getRuntime();
-        this.logger.info("Starting telegram_mcp pair service");
-        this.pairSessionService = new generatePairCode_1.PairSessionService(runtime.config, runtime.stateStore, runtime.stateStore, runtime.stateStore, runtime.logger, runtime.projectIdentityResolver);
-        this.logger.info("telegram_mcp pair service is ready");
-    },
-};
-exports.default = TelegramMcpPairService;

package/dist/services/features/telegram-mcp/src/app/webapp/tmux.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.sendTmuxLiteralText = exports.sendAllowedTmuxAction = exports.isTmuxUnavailableError = exports.getTmuxWindowHeight = exports.captureVisibleTmuxPane = exports.captureTmuxPaneRange = void 0;
-var client_1 = require("../../shared/integrations/tmux/client");
-Object.defineProperty(exports, "captureTmuxPaneRange", { enumerable: true, get: function () { return client_1.captureTmuxPaneRange; } });
-Object.defineProperty(exports, "captureVisibleTmuxPane", { enumerable: true, get: function () { return client_1.captureVisibleTmuxPane; } });
-Object.defineProperty(exports, "getTmuxWindowHeight", { enumerable: true, get: function () { return client_1.getTmuxWindowHeight; } });
-Object.defineProperty(exports, "isTmuxUnavailableError", { enumerable: true, get: function () { return client_1.isTmuxUnavailableError; } });
-Object.defineProperty(exports, "sendAllowedTmuxAction", { enumerable: true, get: function () { return client_1.sendAllowedTmuxAction; } });
-Object.defineProperty(exports, "sendTmuxLiteralText", { enumerable: true, get: function () { return client_1.sendTmuxLiteralText; } });