tele

README

tele

  _            _
 | |_    ___  | |   ___
 | __|  / _ \ | |  / _ \
 | |_  |  __/ | | |  __/
  \__|  \___| |_|  \___|

A terminal-native Telegram client built for keyboard-driven workflows.

Features • Installation • Why tele? • Keybindings • Roadmap

---

Status: Active development — already usable for daily messaging (private chats, groups, replies, reactions). Some Telegram features are still in progress.

---

Why tele?

Telegram Desktop, the web client, and mobile apps are designed around mouse-first interaction.

If you live in the terminal — using tools like Neovim, yazi, k9s, or tmux — switching to a GUI messenger breaks your flow.

tele keeps you in the terminal.

It is built for:

• keyboard-driven navigation
• fast chat switching
• SSH / remote workflows
• distraction-free messaging

If tools like lazygit feel natural to you, tele will too.

It also runs lean — typically ~35MB RSS at idle vs several hundred MB for desktop clients.

---

Feature	tele	Telegram Desktop	Web
Terminal-native	✅	❌	❌
Keyboard-first	✅	⚠️ partial	⚠️ partial
Works over SSH	✅	❌	❌
Single static binary	✅	❌	❌
Full media support	⚠️ photos, voice, video	✅	✅
Voice/video calls	❌ planned	✅	✅

---

Features

⚡ Keyboard-first UX

Vim-inspired navigation (j/k, gg/G, insert mode, etc.)

💬 Full Telegram support

Private chats, groups, channels, replies, reactions, edits.

🎞 Rich media in the terminal

• Photos — rendered inline in high quality via the Kitty graphics protocol, with an ANSI block-art fallback; press o to open in an external viewer.
• Voice messages — amplitude waveform with duration, and in-app playback (p) with an animated playhead. Fully cgo-free on every platform: Opus/Ogg is decoded in pure Go, and audio goes out via oto (macOS/Windows) or the PulseAudio/PipeWire protocol (Linux). On Linux this needs a running PulseAudio or PipeWire server (the desktop default).
• Video & round video (кружки) — inline thumbnail preview with a ▶ / duration overlay (round notes shown as a circle); press o to play in the system player.
• Audio (music) — performer / title / duration; other media types show a labelled placeholder.

🧠 Terminal-native design

Built specifically for terminal workflows — not adapted from a GUI client.

🚀 Lightweight by design

Single static Go binary with fast startup and low memory usage.

⚙ Simple configuration

YAML-based config with sensible defaults.

---

Installation

macOS / Linux — Homebrew

brew tap sorokin-vladimir/tele
brew install tele

Linux — binary

curl -sL https://github.com/sorokin-vladimir/tele/releases/latest/download/tele-linux-amd64 \
  -o ~/.local/bin/tele && chmod +x ~/.local/bin/tele

For arm64: replace amd64 with arm64.

---

First launch

tele

On first run, tele creates:

~/.config/tele/config.yml

Then prompts for:

• phone number
• SMS code
• optional 2FA password

---

Flags

Flag	Description
--config <path>	Path to config file (default ~/.config/tele/config.yml)
-e	Enable debug logging
--trace	Log sensitive metadata (peer IDs, message lengths). Never use on shared or synced file systems
--version	Print version and exit

---

Keybindings

Key	Action
j / k	Navigate chats or scroll messages
i	Compose message
r	Reply
e / d	Edit / delete message
t	React
o / p	Open media externally / play voice
/	Search chats
0 / 1 / 2	Focus panes
q	Quit

Full reference: docs/keybindings.md

---

Configuration

telegram:
  session_file: ~/.config/tele/session.json

ui:
  date_format: "15:04"
  history_limit: 50
  theme: default

Customizing keybindings

Override default keys in the keybindings: section of ~/.config/tele/config.yml. The generated config already lists every action with its current default keys, commented out — just uncomment a line and change the key(s). Bindings are grouped by context, then by action:

keybindings:
  chat:
    reply: "R"              # a single key
    go_top: ["g g", "gg"]   # several keys for one action
  chatlist:
    confirm: "l"

• Replace semantics: the keys you list become the only keys for that action in that context. Actions you don't mention keep their defaults.
• Chords: a multi-key sequence is written as space-separated key tokens — "g g" means press g then g. Tokens use the terminal key names (ctrl+d, enter, esc, space, up, ...).
• Conflicts (an unknown action/context, an empty key, a key reused for two actions, or a single key that shadows a chord) are logged as warnings on startup and skipped or applied last-wins; a bad section never crashes the app.

Contexts: global, folders, chatlist, chat, composer, search, context_menu, delete_submenu.

See docs/keybindings.md for the full list of action names and what each one does.

---

Roadmap

Tracked via GitHub milestones.

Milestone	Focus
Security & Reliability	safer event handling, logging, cleanup
Architecture & Performance	caching, memory caps, optimization
Feature Completeness	forwarding, mentions, drafts, search
Power User & Polish	themes, vim motions, command palette

---

Build from source

Requires Go 1.26+ and your own Telegram API credentials.

git clone https://github.com/sorokin-vladimir/tele
cd tele
go build \
  -ldflags "-X main.buildAPIID=YOUR_API_ID -X main.buildAPIHash=YOUR_API_HASH" \
  -o tele ./cmd/tele/

---

License

GPL-3.0 — free to use and fork; derivative works must remain open-source.

---

Built with:

• gotd/td
• bubbletea
• lipgloss
• inspired by lazygit