A complete Telegram group management bot with a Linux command-line feel, built with Python and aiogram v3. It ships moderation, warnings, notes, filters, locks, greetings and antiflood — plus a Gemini AI core you can switch on and off from a button inside Telegram, and an interface available in 8 languages.
Everything is free, forever. No premium tier, no paid features, no hidden gates. The source is public.
👤 Created by @ham1235i
- 🔑 Automatic roles per group — the moment the bot joins a group it reads the member list and recognises the owner and every admin on its own, then keeps that in sync whenever someone is promoted, demoted or leaves. Each admin starts with permissions derived from their real Telegram rights; the group owner can grant or revoke any single one with a button, and admins can adjust what a member is allowed to send.
- 🧠 AI core with an in-Telegram switch —
/settingsopens an inline panel with a live🧠 AI: ON/OFFbutton. One tap flips the AI for that chat and the panel redraws itself./ai onand/ai offdo the same from text, and the bot owner has a global kill switch. - 🌐 8 interface languages — English (default), فارسی, العربية, Türkçe, Русский, Italiano, 中文, 日本語. Admins set the language per group; each user can set their own in private chat. AI answers follow the chat's language.
- 🛡 Full moderation — ban, timed ban, silent ban, kick, mute, timed mute, promote, demote, pin, purge, user cards.
⚠️ Warning system — per-chat limit and a configurable action (mute / kick / ban) when a member hits it.- 📝 Notes & filters — save messages or media as
#notes, and auto-reply to keywords. - 🔒 Content locks — links, media, photos, videos, stickers, GIFs, forwards, mentions, voice, documents and joining bots.
- 👋 Greetings — welcome and goodbye messages with placeholders, plus service-message cleanup.
- 🌊 Antiflood — act after N consecutive messages from the same member.
- 👥 Alias packages — group members under a name (
devs,mods) and mention them all at once. - 💻 Linux CLI flavour —
whoami,sudo userdel -f @userandclear --terminalwork as real commands.
| Command | Action |
|---|---|
/ban, /sban, /tban 10m |
Ban, silent ban, timed ban |
/unban |
Lift a ban |
/kick, /kickme |
Remove a user, or leave yourself |
/mute, /tmute 30m, /unmute |
Mute controls |
/promote, /demote |
Admin controls |
/pin, /unpin |
Pin controls |
/purge, /del |
Delete up to the replied message, or just it |
/info, /id, /admins, /link |
Chat and user information |
| Command | Action | Who |
|---|---|---|
/staff |
Owner and admins with how many permissions each holds | Everyone |
/sync |
Read the admin list from Telegram again | Settings permission |
/perms |
Panel to grant or revoke a single permission of an admin | Group owner |
/mperms |
Panel to allow or block what a member may send | Mute permission |
Permissions: Ban · Mute · Warn · Delete · Pin · Promote · Settings · Locks · Notes · AI switch · Alias · Permissions
Defaults come from the admin's own Telegram rights — an admin without ban users in Telegram does not get the bot's Ban permission either. Permissions is off by default and only the group creator (or the bot owner) holds it, until they hand it to someone else. Every override is per group, and it is dropped automatically when the person stops being an admin.
Member permissions map onto Telegram's own restrictions: Messages, Media, Stickers & GIFs, Polls, Link previews, Invite, Pin, Chat info.
/warn · /dwarn · /unwarn · /resetwarn · /warns · /warnlimit 3 · /warnmode mute|kick|ban
/save name · /get name · #name · /notes · /clear name · /filter word · /filters · /stop word
/lock <type> · /unlock <type> · /locks
Types: link, media, photo, video, sticker, gif, forward, mention, voice, document, bots
/welcome on|off · /goodbye on|off · /setwelcome <text> · /setgoodbye <text> · /cleanservice on|off
Placeholders: {mention} {first} {last} {username} {id} {chatname} {count}
/antiflood · /setflood 10 · /setflood off · /setfloodmode mute|kick|ban
| Command | Action | Who |
|---|---|---|
/ai <prompt> |
Ask the AI core | Everyone |
/ai on, /ai off |
Turn the AI on or off in this chat | Admins |
/settings → 🧠 button |
The same switch, as a button | Admins |
/aiglobal on|off |
Global switch for every chat | Bot owner |
When the AI is on, replying to one of the bot's messages continues the conversation. In private chat the AI is on by default; in groups it starts off.
/alias add devs @user1 @user2 · /alias run devs · /alias del devs · /alias list
/start · /help · /settings · /lang · /report (or @admin) · /about
| Terminal | Effect |
|---|---|
whoami |
Your identity, chat id and privilege (root / sudoers / user) |
sudo userdel @user |
Kick that user |
sudo userdel -f @user |
Ban that user |
clear --terminal |
Purge messages up to the replied one |
/sudo add|del|list · /stats · /aiglobal · /broadcast <text>
git clone https://github.com/hami9/telegram-linux-bot.git
cd telegram-linux-bot
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txtcp .env.example .env| Variable | Meaning |
|---|---|
BOT_TOKEN |
Token from @BotFather — required |
OWNER_ID |
Your numeric Telegram id (send /id to the bot) |
GEMINI_API_KEY |
Key from Google AI Studio — optional; without it every other feature still works and only the AI replies that it is not configured |
GEMINI_MODEL |
Defaults to gemini-2.5-flash |
DB_PATH |
SQLite file, defaults to data/bot.db |
DEFAULT_LANG |
en, fa, ar, tr, ru, it, zh or ja |
LOG_LEVEL |
INFO, DEBUG, … |
In @BotFather turn Group Privacy off (/setprivacy → Disable) so the bot can see group messages.
python main.pyThen add the bot to your group, promote it to admin with delete messages, ban users and pin messages, and run /settings.
docker build -t linux-terminal-bot .
docker run -d --name linuxbot --env-file .env -v "$PWD/data:/app/data" --restart unless-stopped linux-terminal-bot[Unit]
Description=Telegram Linux Terminal Bot
After=network.target
[Service]
WorkingDirectory=/opt/telegram-linux-bot
ExecStart=/opt/telegram-linux-bot/.venv/bin/python main.py
Restart=always
[Install]
WantedBy=multi-user.targetpip install pytest pytest-asyncio
python -m pytestThe suite checks that all 8 locales carry the same keys and placeholders, that durations and user targets parse correctly, that the database round-trips every setting, and it drives the real dispatcher through a mocked Telegram session — role detection on join, granting and revoking an admin permission, member restrictions, the AI toggle, language switching, warnings, notes, filters, locks and antiflood all run end to end.
main.py entrypoint and dispatcher wiring
bot/config.py environment settings
bot/db.py SQLite storage
bot/middlewares.py language resolution, chat registry, error guard
bot/filters.py admin / group / owner filters
bot/keyboards.py inline panels
bot/constants.py locks, modes, permission sets
bot/i18n/ translation loader and the 8 locale files
bot/services/ Gemini client and rate limiting
bot/handlers/ one module per feature (roles.py holds the role sync and permission panels)
bot/utils/access.py role resolution, effective permissions, staff sync
tests/ pytest suite
۱. مخزن را کلون کن و pip install -r requirements.txt را اجرا کن.
۲. فایل .env.example را به .env کپی کن و BOT_TOKEN و OWNER_ID را بگذار. اگر کلید GEMINI_API_KEY را هم بگذاری، هستهی هوش مصنوعی فعال میشود.
۳. با python main.py ربات را بالا بیاور.
۴. ربات را به گروه اضافه کن، ادمینش کن و /settings را بزن؛ از همانجا با یک دکمه هوش مصنوعی را روشن یا خاموش کن و زبان گروه را از بین ۸ زبان انتخاب کن.
۵. ربات بهمحض ورود، اونر و ادمینهای گروه را خودش میشناسد. اونر با /perms میتواند دسترسی هر ادمین را تکبهتک کم یا زیاد کند و ادمینها با /mperms تعیین میکنند یک ممبر چه چیزی بفرستد. /staff هم لیست کادر مدیریت را نشان میدهد.
Pull requests are welcome — see CONTRIBUTING.md for the setup, the house rules and how to add a language. Bugs and ideas go to Issues; security reports follow SECURITY.md.
Changes per version are listed in CHANGELOG.md.
Released under the MIT License — use it, change it, host it, sell nothing back to your users for it.
Made by @ham1235i — free and open source, every feature, for everyone.