{"id":38708834,"url":"https://github.com/mattmezza/tlgram","last_synced_at":"2026-01-19T22:04:19.180Z","repository":{"id":332377245,"uuid":"1131101234","full_name":"mattmezza/tlgram","owner":"mattmezza","description":"A snappy non-complete but immediately useful TUI client for telegram.","archived":false,"fork":false,"pushed_at":"2026-01-16T15:16:44.000Z","size":440,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T19:51:54.805Z","etag":null,"topics":["cli","telegram","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattmezza.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-09T13:30:18.000Z","updated_at":"2026-01-16T15:16:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mattmezza/tlgram","commit_stats":null,"previous_names":["mattmezza/tlgram"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/mattmezza/tlgram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Ftlgram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Ftlgram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Ftlgram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Ftlgram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattmezza","download_url":"https://codeload.github.com/mattmezza/tlgram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Ftlgram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28587146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T20:45:59.482Z","status":"ssl_error","status_checked_at":"2026-01-19T20:45:41.500Z","response_time":67,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","telegram","tui"],"created_at":"2026-01-17T10:58:32.690Z","updated_at":"2026-01-19T22:04:19.171Z","avatar_url":"https://github.com/mattmezza.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/banner.png\" alt=\"tlgram banner\" /\u003e\n\u003c/p\u003e\n\n# tlgram\n\nA terminal-based Telegram client with vim keybindings, designed for tmux workflows.\n\n## Features\n\n- **Vim keybindings** - Navigate with hjkl, gg/G, Ctrl-d/u, H/L (press `?` for help)\n- **Line-based cursor** - Move through messages line by line, handles wrapped text naturally\n- **Multi-line messages** - Compose multi-line messages (Enter for newline, Alt-Enter to send)\n- **CLI chat opening** - `tlgram --chat @username` or `tlgram --chat work`\n- **Multiple instances** - Run different chats in different tmux panes\n- **Fuzzy chat switcher** - Ctrl-p to search and switch chats (searches names and @usernames)\n- **Chat aliases** - Define shortcuts like `work = \"@john_doe\"`\n- **Smart header bar** - Shows chat type info (DM: name @username, Group: name (x members))\n- **Unread indicator** - Visual badge for unread messages\n- **Notifications** - Custom notification commands (can include terminal bell for tmux visual bell)\n- **Watch/Mute** - Watch (`w`) for priority chats, mute individual (`m`) or all (`M`)\n- **Reactions** - View and add reactions with `1-6` keys (configurable emojis), remove with `0`\n- **Pure Go** - No CGO dependencies, uses gotd/td library\n\n## Installation\n\n### Quick Install (Linux/macOS)\n\n```bash\n# Download and install the latest release\ncurl -fsSL https://github.com/mattmezza/tlgram/releases/latest/download/tlgram_$(uname -s)_$(uname -m).tar.gz | tar -xz -C /usr/local/bin tlgram\n\n# Or with wget\nwget -qO- https://github.com/mattmezza/tlgram/releases/latest/download/tlgram_$(uname -s)_$(uname -m).tar.gz | tar -xz -C /usr/local/bin tlgram\n```\n\n\u003e **Note:** You may need `sudo` for `/usr/local/bin`. Alternatively, install to `~/.local/bin`:\n\u003e ```bash\n\u003e mkdir -p ~/.local/bin\n\u003e curl -fsSL https://github.com/mattmezza/tlgram/releases/latest/download/tlgram_$(uname -s)_$(uname -m).tar.gz | tar -xz -C ~/.local/bin tlgram\n\u003e ```\n\n### Manual Download\n\nDownload the appropriate binary from [Releases](https://github.com/mattmezza/tlgram/releases):\n\n| Platform | Architecture | Download |\n|----------|--------------|----------|\n| Linux | x86_64 | `tlgram_VERSION_linux_amd64.tar.gz` |\n| Linux | ARM64 | `tlgram_VERSION_linux_arm64.tar.gz` |\n| macOS | Intel | `tlgram_VERSION_darwin_amd64.tar.gz` |\n| macOS | Apple Silicon | `tlgram_VERSION_darwin_arm64.tar.gz` |\n| Windows | x86_64 | `tlgram_VERSION_windows_amd64.zip` |\n\n### Windows Installation\n\n1. Download `tlgram_VERSION_windows_amd64.zip` from [Releases](https://github.com/mattmezza/tlgram/releases)\n2. Extract the zip file\n3. Move `tlgram.exe` to a directory in your PATH (e.g., `C:\\Users\\YourName\\bin`)\n4. Or run it directly from the extracted folder\n\n### Build from Source\n\nRequires Go 1.22+.\n\n```bash\n# Clone and build\ngit clone https://github.com/mattmezza/tlgram.git\ncd tlgram\ngo build -o tlgram ./cmd/tlgram\n\n# Install to your PATH\nsudo mv tlgram /usr/local/bin/\n```\n\n### Platform Compatibility\n\n- **Linux** - Fully tested and supported\n- **macOS** - Builds available but untested\n- **Windows** - Builds available but untested (contributions welcome!)\n\n## Quick Start\n\n1. **Get Telegram API credentials**\n   - Go to https://my.telegram.org/apps\n   - Log in with your phone number\n   - Create an application (any name works)\n   - Note your `api_id` and `api_hash`\n\n2. **Configure tlgram**\n\n   **Option A: ~/.secrets file** (recommended - keeps secrets out of dotfiles)\n\n   Create `~/.secrets` (this file should NOT be committed to git):\n   ```bash\n   # ~/.secrets\n   export TLGRAM_API_ID=12345678\n   export TLGRAM_API_HASH=\"your_api_hash_here\"\n   ```\n\n   Source it from your shell rc file:\n   ```bash\n   # Add to ~/.bashrc or ~/.zshrc\n   [ -f ~/.secrets ] \u0026\u0026 source ~/.secrets\n   ```\n\n   **Option B: Config file**\n   ```bash\n   vim ~/.config/tlgram/config.toml\n   ```\n   ```toml\n   [telegram]\n   api_id = 12345678\n   api_hash = \"your_api_hash_here\"\n   ```\n\n   Environment variables take precedence over config file values.\n\n3. **Run tlgram**\n   ```bash\n   # Open chat switcher\n   tlgram\n\n   # Open specific chat\n   tlgram --chat @username\n   ```\n\n4. **Authenticate**\n   - Enter your phone number\n   - Enter the SMS code from Telegram\n   - Enter 2FA password if enabled\n\n## Usage\n\n### Command Line\n\n```bash\ntlgram                     # Open chat switcher\ntlgram --chat @john_doe    # Open DM with @john_doe\ntlgram --chat 1234567890   # Open chat by ID (use I key to find ID)\ntlgram --chat work         # Open chat aliased as \"work\"\ntlgram --help              # Show help\ntlgram --version           # Show version\ntlgram --changelog         # Show changelog\ntlgram --default-config    # Print default config (useful for resetting)\ntlgram --check-update      # Check if a new version is available\ntlgram --update            # Update to the latest version\n```\n\n### Keybindings\n\n#### Navigation (NORMAL mode)\n\n| Key | Action |\n|-----|--------|\n| `j` / `k` | Move cursor down/up by line |\n| `gg` | Jump to first line (loads older messages) |\n| `G` | Jump to last line |\n| `H` | Move cursor to top of visible viewport |\n| `L` | Move cursor to bottom of visible viewport |\n| `Ctrl-d` | Scroll half page down |\n| `Ctrl-u` | Scroll half page up |\n| `Ctrl-f` | Scroll full page down |\n| `Ctrl-b` | Scroll full page up |\n\n#### Modes\n\n| Key | Action |\n|-----|--------|\n| `i` | Enter INSERT mode (compose message) |\n| `A` | Jump to bottom and enter INSERT mode |\n| `Escape` | Return to NORMAL mode |\n\n#### Actions (NORMAL mode)\n\n| Key | Action |\n|-----|--------|\n| `Enter` | Select / Open chat |\n| `Ctrl-p` | Open chat switcher |\n| `r` | Reply to message at cursor |\n| `R` | Mark messages as read up to cursor |\n| `o` | Jump to original message (for replies) |\n| `Ctrl-o` | Jump back after jumping to original |\n| `yy` | Copy message at cursor to clipboard |\n| `cc` | Edit own message at cursor |\n| `D` | Delete own message at cursor |\n| `u` | Toggle between full names and @usernames |\n| `U` | Mark dialog as unread |\n| `I` | Toggle chat ID display in header |\n| `d` | Download media |\n| `1-6` | Add reaction (configurable emojis) |\n| `0` | Remove your reaction |\n| `w` | Watch chat (always notify, bypasses mutes) |\n| `m` | Mute notifications for this chat |\n| `M` | Mute ALL notifications (global toggle) |\n| `?` | Show help screen with all keybindings |\n| `q` | Quit |\n\n#### Chat Switcher\n\n| Key | Action |\n|-----|--------|\n| `Ctrl-p` | Open switcher |\n| `Ctrl-n` | Navigate down |\n| `Ctrl-p` | Navigate up |\n| `Enter` | Select chat |\n| `Ctrl-r` | Mark selected chat as read |\n| `Ctrl-u` | Mark selected chat as unread |\n| `Escape` | Close switcher |\n| Type | Filter chats by name or @username |\n\n#### Insert Mode\n\n| Key | Action |\n|-----|--------|\n| `Enter` | Insert newline (for multi-line messages) |\n| `Alt-Enter` | Send message (stays in INSERT mode) |\n| `Escape` | Exit to NORMAL mode |\n\n## Header Bar\n\nThe header bar displays contextual information based on chat type:\n\n- **DMs**: `NORMAL Name Surname @username` + connection status\n- **Groups**: `NORMAL Group Name (x members)` + connection status\n- **Channels**: `NORMAL Channel Name (x subscribers)` + connection status\n\nWhen there are unread messages, a red badge shows the count on the right side.\n\n## Scroll Indicator\n\nThe bottom of the message view shows a scroll indicator:\n\n```\n↑ ─ line 50/133 ↓ (3 new)\n```\n\n- `↑` / `↓` arrows indicate more content above/below\n- Line position shows current cursor location\n- `(N new)` appears when new messages arrive while scrolled up\n\n## Configuration\n\nConfiguration file: `~/.config/tlgram/config.toml`\n\nTo reset your config or see all options: `tlgram --default-config \u003e ~/.config/tlgram/config.toml`\n\n```toml\n[telegram]\napi_id = 12345678\napi_hash = \"your_api_hash\"\n\n[general]\n# Send key: \"ctrl-enter\" (default, allows multi-line with Enter) or \"enter\"\nsend_key = \"ctrl-enter\"\ndownload_dir = \"~/Downloads/tlgram\"\n# Auto-mark messages as read: -1=disabled (default), 0=instant, \u003e0=delay in seconds\nauto_mark_read = -1\n\n[appearance]\n# Author display: \"fullname\" or \"username\" (toggle with 'u' key)\nauthor_display = \"fullname\"\nreply_preview_length = 30\n# Show chat ID in header (toggle with 'I' key)\nshow_chat_id = false\n\n[notification]\n# External notification command (leave empty to disable)\n# Template variables: %s = sender name, %m = message preview\n# Add echo -e '\\a' for tmux visual bell\ncommand = \"echo -e '\\\\a' \u0026\u0026 notify-send 'tlgram' '%s: %m'\"\n# Start with all notifications muted (toggle with 'M' key)\nstart_muted = false\n\n[reaction]\n# Emojis for quick reactions using number keys 1-6\n# Press 0 to remove your reaction\nemojis = [\"👍\", \"👎\", \"❤️\", \"🔥\", \"🎉\", \"😁\"]\n\n[chat_aliases]\nwork = \"@john_doe\"\nteam = \"-1001234567890\"\n```\n\n## tmux Integration\n\ntlgram is designed to work seamlessly with tmux. Example session setup:\n\n```bash\n# Create a new tmux window with tlgram\ntmux new-window -n telegram \"tlgram --chat work\"\n\n# Split and open another chat\ntmux split-window -h \"tlgram --chat team\"\n```\n\n### Visual Bell for Notifications\n\nAdd `echo -e '\\a'` to your notification command for tmux window highlighting:\n\n```toml\n[notification]\ncommand = \"echo -e '\\\\a' \u0026\u0026 notify-send 'tlgram' '%s: %m'\"\n```\n\nThen in your `~/.tmux.conf`:\n\n```bash\n# Enable visual bell (highlights window name on bell)\nset -g visual-bell on\nset -g bell-action other  # Only trigger for non-current windows\n```\n\nThis will highlight the tmux window name when messages arrive in non-focused chats.\n\n### Watch vs Mute\n\nAll notification toggles are runtime-only (not persisted across restarts):\n\n- `w` - Watch a chat: always notify, even if global mute is on\n- `m` - Mute a chat: suppress notifications for this chat\n- `M` - Global mute: suppress all notifications (except watched chats)\n\n### With hop\n\nIf you use [hop](https://github.com/mattmezza/hop) for tmux session templates, add a `.tmux-session` file to your project:\n\n```bash\n#!/usr/bin/env bash\n# .tmux-session - hop will source this when starting the session\n\ntmux rename-window -t \"$SESSION_NAME:1\" \"code\"\ntmux send-keys -t \"$SESSION_NAME:1\" \"nvim .\" C-m\n\ntmux new-window -t \"$SESSION_NAME\" -n \"telegram\"\ntmux send-keys -t \"$SESSION_NAME:telegram\" \"tlgram -c work\" C-m\n\ntmux select-window -t \"$SESSION_NAME:1\"\n```\n\n## Building\n\n### Requirements\n\n- Go 1.22+\n\n### Build tlgram\n\n```bash\ngo build -o tlgram ./cmd/tlgram   # Development build\ngo test ./...                      # Run tests\n```\n\n## Contributing\n\nContributions are welcome! Please read the contributing guidelines first.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feat/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feat/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [gotd/td](https://github.com/gotd/td) - Pure Go Telegram client library\n- [Bubbletea](https://github.com/charmbracelet/bubbletea) - TUI framework\n- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Styling for TUIs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmezza%2Ftlgram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattmezza%2Ftlgram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmezza%2Ftlgram/lists"}