The Problem
Coding agents like Claude Code and Codex have made it practical to direct development from a phone. The standard remote-access setup—SSH tunnels, VPNs, and tmux sessions—adds friction and fails entirely when an agent needs to inspect graphical output. tgterm replaces that stack with a Telegram bot that screenshots macOS terminal windows and injects keystrokes, so you can drive an agent session from a phone keyboard with zero multiplexing setup.
What This Does
tgterm is a C program that bridges Telegram to your macOS terminal sessions. The core logic lives in bot.c and botlib.c; botlib.c handles the Telegram Bot API interaction, and bot.c wires it to macOS-specific screen capture and keystroke injection. The repo vendors its dependencies directly: cJSON.c for JSON parsing, sqlitewrap.c for persistence, qrcodegen.c for TOTP QR codes, and sds.c for string handling.
The bot authenticates via TOTP. On first run it prints a QR code and secret to the terminal; the first user to message the bot becomes the owner and must enter a 6-digit code. After that, commands like .list enumerate terminal windows and .2 connects to one, letting you send arbitrary text as keystrokes. macOS permissions for Screen Recording and Accessibility are required.
How To Use It
The Makefile is the only build entry point. Dependencies are libcurl and libsqlite3; everything else is vendored. There is no config file—the Telegram API key is passed as a CLI flag.
Build
make
Run (first run prints TOTP QR code and secret) ./tgterm --apikey <your-api-key>
After starting, send any message to the bot from Telegram. The first sender becomes the owner and must authenticate with the TOTP code. Then use .list to see terminal windows and .help for the full command set. The README documents the macOS permission prompts; if screenshots or keystrokes fail silently, check System Settings → Privacy & Security.
Real-World Use
A typical workflow: you're away from the desk, a long-running agent build needs a course correction. You open Telegram, send .list to find the terminal running the agent, connect with .2, and type a follow-up instruction like fix the failing test in testutils.c and rerun. The bot sends a fresh screenshot so you can verify the agent's output before sending the next instruction. No SSH, no tmux, no VPN.
Code Health & Issues
Med – No tests. The repo has zero test files. Security-sensitive code (TOTP, Telegram auth, keystroke injection) is entirely untested. Med – No CI/CD. No GitHub Actions or equivalent pipeline. No automated build or test gate exists. Low – Single-platform constraint. The code is macOS-only by design (screen capture and Accessibility APIs), so the portability story is nil. That's stated in the README, not a hidden defect. Low – Security model. The TOTP secret is printed once to the terminal and never stored in a config file—good—but the owner is determined by "first message wins," which is a race condition if the bot is exposed before you message it. Low – Dependency hygiene. Vendored C libraries (cJSON, sds, qrcodegen) are unversioned snapshots. No pinned versions or update path.
The Bottom Line
A focused, pragmatic tool that solves a real workflow gap for macOS-based agent development. The codebase is small and readable, but the lack of tests and CI makes it a personal tool rather than something you'd deploy broadly. If you run coding agents on a Mac and want phone-based control without SSH overhead, this is worth a look; expect to add your own test coverage before relying on it.