Kiro Telegram Bot 🤖

Control Kiro CLI from Telegram. Your AI coding assistant in your pocket — switch projects, resume and attach to live coding sessions, stream answers with diffs, queue follow-ups, and run it 24/7 as a background service on Windows, Linux, and macOS.

A professional Telegram bridge for the Agent Client Protocol (ACP) that turns Kiro CLI into a mobile, always-on AI pair programmer. Send a message from anywhere and watch Kiro read files, run commands, and edit code on your machine — with live typing indicators, clean Telegram markdown, and unified edit diffs.

Inspired by ajitnk-lab/kiro-acp-telegram-bot and extended into a full multi-session client.

---

✨ Features

| Capability | What it does | |---|---| | 🗂 Projects | /projects browses your folders and runs Kiro in the one you pick. | | ♻️ Resume sessions | /sessions lists recent Kiro sessions; tap to resume via ACP session/load. | | 🟢 Connect to live sessions | /active shows sessions running right now on your PC. Watch them live, or continue them — see below. | | 🛑 Kill a session / PID | Each live /sessions · /active card has a 🛑 Kill · pid N button (confirm-guarded) that stops that session's process and its child tree; /killall stops them all. The bot's own agent is never killable. | | 📡 Live watch | Follow a running session read-only in real time (tails its event log). | | 🧭 Always-visible menu | A persistent keyboard plus a pinned status panel that appears while a task runs (and clears when idle), showing your current project, agent, reasoning effort, model, session and queue. | | ⏰ Scheduled tasks | Create prompts that run on a schedule (once / daily / weekly / monthly / every-N-minutes) in a chosen project, delivered back to your chat. | | 🖼 Multi-image prompts | Send one or many photos (albums included) with a caption — all attached to the prompt for the agent to analyze. | | 📜 History | /history shows the latest messages of any session. | | 🧩 MCP control | /mcp lists MCP servers, health-checks them (which connected / failed and why), and enables/disables them — then restarts the agent to apply. | | 👥 Subagent visibility | When Kiro delegates to subagents and waits on them, you see each one start / work / finish plus a live 🤖 N running summary — and subagent permission prompts route to your chat. | | 📈 Task progress bar | The agent appends a {progress: N%} marker; the bot hides it and shows a green 0–100% loading bar on the live message, in the status panel, and on session cards (SHOW_PROGRESS). | | 🔐 Re-auth from chat | /reauth logs you in without a terminal — pick Your organization, Builder ID, Google/GitHub, IAM Identity Center, or Import from Kiro IDE; the URL/code streams to your chat and the agent restarts. | | 👥 Multiple accounts | /accounts saves several Kiro logins (custom names) and switches between them in a tap — copies the token in and restarts so sessions re-bind under the new account. | | 🔁 Auto-rotate on give-up | When a turn exhausts its retries, optionally cycle through your other saved accounts once and retry on each — the first that works wins (toggle in /accounts). | | 🪙 Credits & usage | The ✅ Done line and /usage show credits used (when Kiro reports them), turns this session, and account info. | | ⌨️ Typing indicator | Stays on for the whole turn, even through long tool chains. | | 📥 Queued follow-ups | Message while Kiro is busy — it's queued and runs next. /btw runs it ASAP (now if idle, else right after the current task); /flush runs the queue now. | | ✏️ Edit diffs | File edits show as unified diff blocks with +N -M stats. | | 💬 Quality markdown | Converts agent markdown to Telegram MarkdownV2 with safe escaping and code-fence-aware splitting. | | 🔁 Self-healing | Auto-restarts the Kiro agent with backoff and re-binds your session. | | 🖥 Runs 24/7 | 1-click install as a background service that starts on boot — Windows, Linux, macOS, auto-detected. | | 🔒 Access control | Restrict to specific Telegram user IDs. |

---

📊 How it compares

| Capability | This bot | Other Kiro Telegram bots | |---|:---:|:---:| | Connect Kiro CLI to Telegram (ACP) | ✅ | ✅ | | Switch between projects | ✅ | ❌ | | Resume saved sessions | ✅ | ❌ | | Attach to live PC sessions (watch / fork) | ✅ | ❌ | | Kill a session by PID (or all at once) | ✅ | ❌ | | Live task-progress bars ({progress: N%}) | ✅ | ❌ | | Re-authenticate from chat (/reauth, device flow) | ✅ | ❌ | | Multiple saved accounts + one-tap switch (/accounts) | ✅ | ❌ | | Auto-rotate accounts when a turn gives up | ✅ | ❌ | | Multiple isolated sessions | ✅ | ❌ (single shared) | | Queued follow-ups while busy | ✅ | ❌ | | Scheduled tasks (cron-like) | ✅ | ❌ | | Multi-image prompts (albums) | ✅ | ❌ | | Unified edit diffs | ✅ | ❌ | | Persistent menu + live status panel | ✅ | ❌ | | Agent / reasoning / model menus | ✅ | ❌ | | Combined, throttled output (no spam) | ✅ | ❌ | | Auto-restart + session re-bind | ✅ | ❌ | | 24/7 cross-platform service | ✅ | ❌ | | 1-click install | ✅ | ❌ |

---

⚡ Install from npm

The fastest way — one command installs the global kiro-tg CLI (ships with the tsx runtime, no build step):

npm install -g kiro-telegram-bot

By default your config lives in a canonical, path-independent home — ~/.kiro/tg/ (its .env, logs/, data/) — so the bot loads the same .env no matter which folder you start it from. Run kiro-tg setup --path to print the exact location. (A .env in the current folder is still honoured first, so existing per-folder checkouts keep working.)

kiro-tg setup            # auto-detects kiro-cli, writes ~/.kiro/tg/.env
kiro-tg setup --path     # print the .env location
# edit that .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
kiro-tg run              # foreground …
kiro-tg install          # … or install as a 24/7 background service

The bot is single-instance per token: starting it again terminates any ghost/duplicate that was still polling Telegram (the usual cause of a stale "⛔ Not authorized"), so the fresh process with your current .env wins. A plain kiro-tg run yields to an already-running background service instead.

Startup options: kiro-tg setup [--path] | run | install | status | logs [n] | stop | restart | uninstall. Or try it without installing: npx kiro-telegram-bot setup. See docs/INSTALL.md for the full guide.

Already installed? See docs/UPGRADE.md to update to the newest version — global npm installs auto-update when idle, or run npm install -g kiro-telegram-bot@latest and kiro-tg restart.

---

🚀 1-click install

Clone or download, then run the installer for your OS. It installs dependencies, auto-detects kiro-cli, writes .env, asks for your bot token, and optionally sets up the background service.

Windows — double-click install.cmd (or in a terminal):

.\install.cmd

Linux / macOS:

chmod +x install.sh && ./install.sh

Prerequisites

• Kiro CLI installed and authenticated — run kiro-cli chat once to confirm.
• Node.js 20+.
• A bot token from @BotFather.
• Your Telegram user ID from @userinfobot.

---

🧑‍💻 Manual setup

npm install
npm run setup            # auto-detects kiro-cli + project roots, writes .env
# edit .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
npm start

No build step — TypeScript runs directly via tsx.

---

🛠 Run as a background service (daemon)

The bot installs as a user-level service that starts automatically on boot. The platform is auto-detected:

| OS | Mechanism | Starts on | |---|---|---| | Windows | Hidden Scheduled Task (elevated) · per-user Startup folder (no admin) | logon | | Linux | systemd user service (+ linger) | boot | | macOS | launchd LaunchAgent | login |

On Windows, registering a logon-triggered Scheduled Task needs admin, so from a normal terminal kiro-tg install falls back to a hidden launcher in your per-user Startup folder (starts at logon, no elevation). Run it from an elevated terminal to use the Scheduled Task instead; either way status, stop, restart and uninstall work the same.

npm run install:service     # install + start, enable autostart
npm run service -- status   # show install + running state
npm run service -- stop
npm run service -- restart
npm run service -- logs 200 # tail the log file
npm run uninstall:service   # stop + remove

Or use the kiro-tg command (if linked): kiro-tg install | status | logs.

Logs are written to logs/kiro-telegram-bot.log (rotated at 5 MB).

---

🐳 Docker

Prefer containers? The image bundles the bot and Kiro CLI (latest stable at build time), runs as an unprivileged user, and keeps sessions + your Kiro login in named volumes:

cp .env.example .env          # set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
mkdir -p workspace            # projects the agent can work on (mounted at /workspace)
docker compose up -d --build

Then log in to Kiro from Telegram with /reauth (or set KIRO_API_KEY on a paid plan). Auth options, volumes, updating and security notes are in docs/DOCKER.md.

---

💬 Commands

/menu         Show the persistent menu keyboard
/projects     List · /projects <q> search · /projects <path> open any folder · /projects new <name>
/sessions     List & resume sessions (active first) · /sessions <q> to filter
/active       Sessions running now on the PC
/running      Sessions this chat controls — switch between them
/killall      Kill all active sessions on the PC (with confirm)
/mcp          Inspect MCP servers · health-check · enable/disable
/tasks        Manage scheduled tasks
/newtask      Create a scheduled task (wizard)
/history      Show recent conversation history
/export       Download the full session transcript (.md · /export txt for plain text)
/new          Start a fresh session here
/status       Current session, project & queue
/usage        Account info & current context usage
/btw <text>   Run it now if idle, else queue to run right after the current task
/flush        Send queued follow-ups now
/queue        Show queued follow-ups
/clearqueue   Clear the queue
/cancel       Stop the current turn
/unwatch      Stop following a live session
/model <id>   Switch the model for this session
/restart      Restart the Kiro agent
/reauth       Log in to Kiro — organization / Builder ID / Google / GitHub / IAM Identity Center / import from Kiro IDE
/accounts     Save & switch between multiple Kiro accounts · auto-rotate on errors
/help         Show help

Anything that isn't a command is sent to Kiro as a prompt. While a turn is running, your messages are queued and sent automatically when it finishes.

---

🧭 The menu & status panel

A tiny persistent bar sits under the message box — ☰ Menu · 🧭 Running · ⏹ Stop — so common actions are one tap away without clutter. Tap ☰ Menu (or /menu) to open a clean, grouped inline menu: Project · New · Running · Sessions · Agent · Model · Reasoning · Tasks · Status · Usage · Stop · Kill all. The bar can be hidden (🙈) and restored (⌨️ Show bar or /menu).

While a task is running, a pinned status panel appe