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

📊 How it compares

🚀 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:

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).

💬 Commands

/menu         Show the persistent menu keyboard
/projects     List projects · /projects <q> search · /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)
/tasks        Manage scheduled tasks
/newtask      Create a scheduled task (wizard)
/history      Show recent conversation history
/new          Start a fresh session here
/status       Current session, project & queue
/usage        Account info & current context usage
/btw <text>   Queue a follow-up to run 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
/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).

A pinned status panel at the top of the chat always shows your current
project, agent, reasoning effort, model, session id, context %, activity and
queue (and how many sessions the chat controls), updating live. Pick Agent,
Reasoning or Model from the inline menu (reasoning steers how thoroughly
the agent works: Minimal → Max).

⏰ Scheduled tasks

A task is a prompt + a project + a schedule. When it fires, the bot opens a
session in that project, runs the prompt, and delivers the result to your chat.

• /newtask (or the ➕ button) launches a guided wizard: name → prompt →
  project → schedule → confirm.
• Schedules: once at a date/time, daily at HH:MM, weekly (e.g. Mon 09:00),
  monthly (e.g. 15 09:00), or interval (every N minutes).
• /tasks lists everything with buttons to run now, enable/disable, edit
  (rename, prompt, project, reschedule) and delete.

Tasks are stored in data/tasks.json and survive restarts; the scheduler runs
them whether you're online or not (great with the 24/7 service).

🖼 Sending images

Send one or several photos — including a Telegram album — with an optional
caption. The bot downloads them and attaches them all to the prompt as image
content blocks, so the agent can analyze them together. Images sent while Kiro
is busy are queued with your next turn.

Images come back too: when the agent produces images during a turn (e.g.
takes screenshots while testing an app), the bot detects the freshly-written
files and sends them back to Telegram automatically (SEND_AGENT_IMAGES).

🎙 Sending voice

Send a voice note (or audio file) and the bot transcribes it and runs it as a
prompt. Configure any OpenAI/Whisper-compatible endpoint via STT_API_URL in
.env; leave STT_LANGUAGE blank for automatic detection (English, Russian,
Romanian/Moldovan, and ~100 more).

🧭 Working on several sessions at once

One chat can drive multiple Kiro sessions and switch between them. Start a
session (📁 Project / 🆕 New), and each becomes a "controlled" session. Tap
🧭 Running (or /running) to switch: the foreground session streams live
while the others keep working quietly. When you switch to a session you see its
recent context and every message that arrived while you were away (its
unread, recovered from the session log). Leave a task running in A, hop to B,
reply, and come back to A to read what it did. Close a session with ✖ (it isn't
killed — see /killall for that).

🔗 Connecting to live sessions

Kiro keeps an exclusive lock on a session while it's running, so a second
client cannot hijack a session that's open in another window. This bot handles
that honestly:

• 📡 Watch — follow the running session's output live (read-only) by tailing
  its event log. Stop with /unwatch.
• Continue (fork) — tapping a live session opens a linked continuation in
  the same project, primed with the recent transcript, so you can keep
  interacting from Telegram without disturbing the original.

Resuming an idle session loads it directly so you continue the exact thread.

⚙️ Configuration (.env)

🧩 How it works

Telegram  ──HTTPS──▶  Bot (grammY)
                         │  spawns once
                         ▼
                 kiro-cli acp  ◀── JSON-RPC 2.0 over stdio ──▶  Bot
                         │
                         ├─ session/new / session/load   (projects, resume)
                         ├─ session/prompt               (your messages)
                         └─ session/update notifications (streamed text, tools)

One kiro-cli acp process multiplexes many sessions (one per chat/project).
Streamed agent_message_chunk updates are assembled into a live, throttled
message; tool_call updates render as professional status lines with diffs.

Kiro persists sessions to ~/.kiro/sessions/cli/:
<id>.json (metadata), <id>.jsonl (history, used by /history and live
watch), and <id>.lock ({ pid }, used to detect active sessions).

📁 Project layout

src/
├── index.ts              Entry point, daemon-friendly logging, shutdown
├── cli.ts                CLI: run / install / start / stop / status / logs
├── config.ts             .env loading, paths, daemon options
├── logger.ts             Leveled logger with file output
├── acp/                  ACP client, transport, server-side handlers, types
├── sessions/             Session discovery, history parser, live tail watcher
├── projects/             Project directory discovery
├── render/               Markdown→MarkdownV2, diffs, tool formatting, chunking
├── stream/               Incremental edit-streaming
├── service/              Cross-platform daemon (windows/linux/macos + selector)
└── bot/                  grammY bot, per-chat runtime, handlers

❓ FAQ

Can I run the Kiro Telegram bot 24/7 on a server? Yes — npm run install:service
installs a user-level service (systemd/launchd/Scheduled Task) that starts on
boot and auto-restarts on crash.

How do I control Kiro from my phone? Set up the bot, message it on Telegram,
and pick a project with /projects. Every message becomes a Kiro prompt.

Can multiple people use one bot? Add their IDs to ALLOWED_USERS. Each chat
gets its own session.

Why can't I take over a session that's already running? Kiro locks active
sessions exclusively. The bot lets you watch it live or fork a linked
continuation instead. See "Connecting to live sessions".

Does it support custom agents and MCP servers? Yes — set KIRO_AGENT, and
the bot inherits whatever MCP servers Kiro CLI is configured with.

🔐 Inline approvals

The bot implements ACP session/request_permission: when Kiro asks the client
to approve a risky tool call, it appears in Telegram with Approve / Approve
always / Deny buttons and your choice is sent back (unanswered prompts time
out and are denied).

Note: Kiro CLI 2.8.1 resolves tool permissions internally (via
~/.kiro/settings/permissions.yaml and agent config) and does not yet
delegate them over ACP, so these prompts stay dormant on current Kiro. The
wiring is forward-compatible and activates automatically when Kiro emits
permission requests. Today, use the live tool stream + ⏹ Stop to
intervene, and permissions.yaml to govern what Kiro may do.

🔐 Security

This bot lets authorized Telegram users run commands and edit files on the host.
Always set ALLOWED_USERS, keep .env private, and run as a non-privileged
user. See SECURITY.md for the full model.

🗺 Roadmap

• Projects, resume & attach to live sessions
• Queued follow-ups, edit diffs, quality MarkdownV2
• Persistent menu + live status panel (project / agent / reasoning / model)
• Scheduled tasks (once / daily / weekly / monthly / interval)
• Multi-image prompts (albums)
• Combined, throttled output (anti-spam)
• 24/7 cross-platform background service
• Voice messages → speech-to-text → prompt (multi-language)
• Context-usage % in the status panel
• Inline approvals — approve/deny risky tools from buttons (non trust-all mode)
• Account & context usage (/usage)
• Release automation — downloadable zip + CHANGELOG-driven notes on tag push
• README community sections — Contributors, Top Contributors, Stars, StarMapper
• Token & cost meter — per-session token counts and an estimated spend tally
• Text-to-speech replies — optionally speak answers back as voice notes
• Scheduled-task chaining & conditions — run task B after A, or only if a command/file check passes
• Team mode — multiple authorized users with per-user sessions, roles, and an audit log
• Localized bot UI (i18n)
• Docker image with kiro-cli preinstalled
• Webhook mode for serverless deployment

Have an idea? Open a feature request.

🤝 Contributing

Contributions are very welcome! See CONTRIBUTING.md to get
started — no build step is required (npm run dev), and npm run typecheck must
pass.

New here? Look for issues labeled
good first issue
and help wanted.

By participating you agree to the Code of Conduct.

👥 Contributors

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

Releasing a New Version

# Bump the version, update CHANGELOG.md, then push a tag.
# The release workflow builds a downloadable zip and publishes notes automatically.
npm version minor              # or: patch / major — updates package.json + commits
git push --follow-tags         # pushing the v* tag triggers .github/workflows/release.yml

⭐ Top Contributors

This project is built and maintained in the open. These people have made the
contributions that shape its quality, stability, and reach. Thank you.

artickc 🥇 Maintainer Created the bot: ACP client, multi-session runtime, scheduler, daemon & renderer

🙏 Every pull request, bug report, and idea matters. Open source is built by
people like them — see the full list under Contributors.

📊 Stars

If this project helps you, please consider giving it a ⭐ — it really helps!

🌍 StarMapper

See where in the world this project's stargazers live — an interactive map of
the community.

📦 Download & Releases

Grab the latest packaged build from the
Releases page — each
release ships a clean kiro-telegram-bot-<version>.zip (no node_modules or
secrets) plus GitHub's source archives. See CHANGELOG.md for
what changed in each version, and docs/INSTALL.md for the
full 1-click install guide.

📄 License

MIT — see also CONTRIBUTING and
Code of Conduct.

_{Keywords: Kiro CLI Telegram bot, ACP Agent Client Protocol, AI coding
assistant on Telegram, mobile AI pair programming, remote coding agent, run AI
agent as a service, Windows/Linux/macOS daemon, ChatOps for developers.}