A Telegram chat tool for neovim, similar to telega.el

Backend powered by TDLib + Node.js (TypeScript), frontend in pure Lua with HTTP + WebSocket communication.

💬 Join the discussion on Telegram: t.me/+h4aEOaABJJ1mMzhl

Partial screenshots — see Feature Status below for the full list.

• Login with phone number, verification code, and 2FA password
• Session persists across restarts (no re-login)
• :TgLogout to clear auth and start fresh
• Group list with unread badges, inline fuzzy search (Snacks picker with vim.ui.select fallback)
• Open/close chats, switch between groups
• Scroll infinitely in both directions (older and newer messages)
• Receive new messages in real-time via WebSocket
• Typing indicators and online member count
• Cursor position is remembered per chat (tracked by message ID)
• Messages are marked as read when opening a chat; per-message read tracking with last_read_id persistence
• Unread-aware loading — opens at first unread message with unread divider
• Date separators between messages, loading indicators, and empty state
• Send plain text messages (with reply context)
• Send messages with formatting — type markdown syntax (**bold**, ### heading) in input; Telegram clients (Android, iOS, Desktop) parse markdown natively, Neovim buffer renders via markdown treesitter
• Edit your own messages
• Delete your own messages (Delete for me / Revoke for everyone)
• Forward messages to another chat
• Reply to a message with quote context
• Search messages and jump to the result position
• URLs are highlighted and clickable
• Code blocks (backtick) are detected and formatted
• Single-panel chat layout with floating input popup
• Adjustable panel position — panel_position option ("right", "left", "bottom", "top"); width via g:telegram_width (default 50), height via g:telegram_height (default 15)
• ? opens a help popup with all keybindings
• Target line highlighting (reply/edit/delete/forward) using theme's Diff* colors
• :TgPr — create GitHub PR with branch picker, auto-fill, optional merge
• :TgIssue — list, create branch, close, assign, open in browser
• Proxy support (SOCKS5 / HTTP) for restricted regions
• Service messages shown as readable text with prefix symbols
• Download HD media — @refreshmedia downloads highest-quality version of photos/videos under cursor (async, non-blocking)
• Context-aware tool picker — @ only shows applicable tools (e.g. refreshmedia only on media messages)
• Wake-up safe — messages received after sleep are batched and rendered at once, no Neovim freeze
• Admin custom titles — shows [头衔] next to admin names in messages and member list; admins without title show [Administrator]
• Photo / sticker / video / file inline preview — rendered as ![Photo](/path) markdown; works with image renderers like snacks.nvim image module
• Private chats (direct 1-on-1 messages) — press c on a message to open DM with the sender
• Channel support — view channels and their messages; admin tools (member list, change info) shown based on permissions
• Group management — view members (including admins and creator), ban/unban, restrict/unrestrict, promote/demote admins, add members by @username
• Group settings — change title/description, granular default permissions editor (14 permission types with toggle-all), leave group, unsubscribe from channel, delete history
• Invite links — create (with optional member limit and expiration), view, edit, and revoke invite links
• Pin / unpin messages — press p on a message to pin/unpin; permission check for can_pin_messages
• React to messages — press r to open reaction picker with 40+ verified emojis; same emoji toggles off, different auto-switches; real-time sync via WebSocket
• Real-time sync between devices — edits, deletions, reactions, group info changes, user name/status changes sync via WebSocket from other clients
• Online status — session reports as online with periodic heartbeat; device shown as telegram.nvim in Telegram's active sessions list
• Favorites (Saved Messages) — dedicated chat with 📌 icon in picker; press s on any message to save with confirmation
• View counts — channel messages show 👀 N footer with k/M formatting; real-time update via WebSocket
• Read receipts — outgoing private messages show (read HH:MM) in header when read by recipient
• Edited indicator — edited messages show [edited] footer
• Copy message text — press yy to copy message text to system clipboard
• Toggle title bar — @toggleheader shows/hides the floating title bar; configurable via hide_title option
• Connection status — title bar shows red dot when disconnected from Telegram
• Input editor redesign — bottom panel with context preview; markdown syntax highlighting while typing
• Customizable keymaps — all keys configurable via setup({ keys = { ... } })
• Configurable panel position — panel_position = "right" | "left" | "bottom" | "top"
• Theme adaptation — all highlight groups derive from your Neovim theme (Comment, DiffAdd, DiagnosticOk, etc.)

• Send media (photos, videos, files, audio) — can't upload anything yet
• Send stickers / GIFs
• Create polls
• Scheduled messages
• Poll, contact, location, dice, game, call display — fallback shows label, content not interactive
• Inline bots / bot commands

require("telegram").setup({
  keys = {
    input_editor = "I",  -- rebind i → I
    refresh = "<F5>",
    help = "<F1>",
    ban = false,  -- disable ban key
  },
})

All available keys and their defaults:

Set any key to false to disable it.

System messages (members added, group renamed, etc.) are rendered as readable text with a prefix symbol. The text color follows the Comment highlight group.

Media messages are shown as thumbnails or tags:

• Node.js (>= 18)
• curl
• libtdjson — TDLib shared library (minimum version 1.8.64) — libtdjson.so (Linux), libtdjson.dylib (macOS), tdjson.dll (Windows)
• snacks.nvim — optional, used for the chat picker with fuzzy search (falls back to vim.ui.select if not installed)
• ImageMagick — optional, required by snacks.nvim image module to display non-PNG images (e.g. JPEG photos). Install with brew install imagemagick on macOS
• gh (GitHub CLI) — optional, required for :TgPr and :TgIssue commands

git clone https://github.com/tdlib/td.git
cd td
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=~/.local \
    -DCMAKE_CXX_FLAGS="-O2 -g0" \
    ..
cmake --build . --target install -j$(nproc)
ldconfig 2>/dev/null || true

{
  "ChuYanLon/telegram.nvim",
  build = "npm i",
  event = "VeryLazy",
  dependencies = {
    -- "folke/snacks.nvim",   -- optional: enables fuzzy-find chat picker
  },
  keys = {
    { "<leader>tt", "<cmd>Tg<Cr>", desc = "Toggle Telegram" },
    { "<leader>tL", "<cmd>TgLogout<Cr>", desc = "Logout Telegram" },
    { "<leader>tp", "<cmd>TgPr<Cr>", desc = "Create PR" },
    { "<leader>ti", "<cmd>TgIssue<Cr>", desc = "Manage Issues" },
  },
  cmd = {
    "Tg",
    "TgLogout",
    "TgPr",
    "TgIssue",
  },
  opts = {
    -- tdlib_path = "/path/to/libtdjson.so",         -- optional: .so (Linux) / .dylib (macOS) / .dll (Windows)
    -- proxy = "socks5://127.0.0.1:7890",             -- optional: for regions where Telegram is blocked
  },
}

build = "npm i" installs Node.js dependencies automatically on first install.

require("telegram").lualine is a pre-built lualine component:

require("lualine").setup({
  sections = {
    lualine_x = { require("telegram").lualine },
  },
})

For other statuslines (heirline, feline, etc.):

require("telegram").status()       -- "disconnected" | "connecting" | "connected" | "error"
require("telegram").status_color() -- { fg = "#..." }   -- color matching current status
require("telegram").total_unread() -- total, mentions   -- unread counts across all chats

Displays  with:

• 🟢 green — connected, no unread
• 🟡 yellow — connecting
• ⚫ gray — disconnected
• 🔴 red — error or has @mentions
• Shows unread count after icon when there are new messages, e.g.  5
• Appends ! when there are @mentions, e.g.  3!

The server runs on ports 8080/8081 (configurable via setup({ http_port, ws_port }) or TG_PORT/TG_WS_PORT env vars). Opening :Tg in another Neovim instance will connect to the same server — only the instance that started it will stop it on exit.

-- Configure inside lazy.nvim `keys`, or map manually:
vim.keymap.set("n", "<leader>tt", "<cmd>Tg<Cr>", { desc = "Toggle Telegram" })
vim.keymap.set("n", "<leader>tL", "<cmd>TgLogout<Cr>", { desc = "Logout Telegram" })
vim.keymap.set("n", "<leader>tp", "<cmd>TgPr<Cr>", { desc = "Create PR" })
vim.keymap.set("n", "<leader>ti", "<cmd>TgIssue<Cr>", { desc = "Manage Issues" })

In the chat picker (@ → chats):

• Built-in fuzzy search (Snacks picker when available, vim.ui.select fallback)
• <CR> — select chat
• <Esc> — close

First run of :Tg:

1. Backend starts on port 8080
2. TDLib enters authentication flow
3. Neovim shows an input prompt — async and non-blocking, you can keep editing
4. Enter: phone number → verification code → (optional) 2FA password
5. On success, the group list opens automatically

Cancelling the input prompt (ESC / close dialog) aborts auth and cleans cached state. The next :Tg starts from scratch.

Pass options via setup():

require("telegram").setup({
  -- tdlib_path = "/path/to/libtdjson.so",  -- only if auto-detection fails
  -- proxy = "socks5://127.0.0.1:7890",     -- proxy for TDLib connections
  -- data_dir = "/path/to/data",            -- default: plugin root
  -- http_port = 8080,                      -- HTTP server port
  -- ws_port = 8081,                        -- WebSocket server port
  -- notify_chat_types = { "private", "mention" },  -- types: "private", "group", "channel"; add "mention" for @mentions
  -- hide_title = false,  -- start with floating title bar hidden
  -- panel_position = "right",  -- "right" | "left" | "bottom" | "top"
})

Environment variable overrides:

The server auto-detects libtdjson on startup via:

• Linux: ldconfig -p, common paths (/usr/lib, /usr/local/lib, ~/.local/lib, /usr/lib64, /opt/lib), LD_LIBRARY_PATH, and find
• macOS: mdfind and common paths (/opt/homebrew/lib, /usr/local/lib)
• Windows: where tdjson.dll and common paths (%LOCALAPPDATA%, %PROGRAMFILES%)

Override with setup({ tdlib_path = "..." }) or the TG_TDLIB_PATH env var.

Note on proxy: In regions where Telegram is blocked (e.g. China), TDLib cannot connect to Telegram's servers directly. Set a SOCKS5 or HTTP proxy here. Supported formats:

• socks5://127.0.0.1:7890
• socks5://user:pass@127.0.0.1:7890
• http://127.0.0.1:8080

Q: Verification code never arrives (SMS not received) A: If you're in a region where Telegram is blocked (e.g. China), TDLib needs a proxy to connect. Set proxy in your config:

require("telegram").setup({
  proxy = "socks5://127.0.0.1:7890",
})

Your proxy needs to support SOCKS5 (e.g. ClashX, V2Ray, Shadowsocks). On Windows, a system-level VPN/proxy may already cover TDLib's traffic; on macOS, TDLib ignores system proxy settings and must be configured explicitly.

Q: "libtdjson.so not found" / "Cannot find libtdjson" A: The server auto-detects the library on startup. If auto-detection fails, install TDLib (see "Installing libtdjson" above) or set a custom path via setup({ tdlib_path = "..." }) or the TG_TDLIB_PATH env var.

Q: Do I need to re-authenticate every time Neovim restarts? A: No. TDLib caches session state in tdlib_db/. Auth persists across restarts.

Q: Why does the server use TypeScript? A: The backend was migrated from JavaScript to TypeScript (v0.3.0) for better type safety and maintainability in a multi-contributor project. The server runs via tsx, which is installed automatically by npm install — no extra setup needed.

Q: How do I switch accounts? A: Run :TgLogout, or manually delete the tdlib_db/ and tdlib_files/ directories.

Q: Port conflict? A: Default ports are 8080/8081. Configure via setup({ http_port = ..., ws_port = ... }) or TG_PORT/TG_WS_PORT env vars. The plugin checks if a server is already running and reconnects if it's ours. If occupied by another process, startup fails — change to different ports. Server process is terminated on Neovim exit.

• main — stable branch, protected, no direct pushes
• feat/* / fix/* / chore/* — feature/fix branches, created from main
• PRs target main — use :TgPr to create and optionally merge
• Merge options: squash or commit
• After merge, GitHub auto-deletes the source branch (set in repo settings)
• CI runs on every push and PR (test + typecheck)

All contributions are welcome! Just open a pull request targeting main. See the full guide for details.

MIT