gramit 0.5.0

A tool to bridge local CLI applications with a remote Telegram interface.

Gramit: The Ultimate Telegram-to-Terminal Connector

Gramit is the most beautiful, robust, and secure way to bridge your local CLI applications with a remote Telegram interface. It allows you to run any command on your machine—from simple scripts to complex TUIs—and interact with it from anywhere in the world.

[!CAUTION] SECURITY WARNING: REMOTE ACCESS RISK

Gramit provides a bridge between your local machine and a remote Telegram interface. This allows remote command execution.

If you run a shell (like /bin/bash or cmd.exe) or any interactive tool through Gramit, anyone with access to your Telegram bot (and whose Chat ID is authorized) has full control over your machine.

USE ONLY IF YOU ARE HIGHLY SECURITY-AWARE.

• Never share your GRAMIT_TELEGRAM_TOKEN.
• Ensure your GRAMIT_CHAT_ID is correctly configured to your ID only.
• Be extremely cautious when bridging shells or administrative tools.

---

🌟 Key Features

🚀 Dual Output Modes

Gramit offers two powerful ways to bridge your terminal output to Telegram:

1. Standard Mode (IO): Directly captures the stdout of your process via a Pseudo-Terminal (PTY). Perfect for line-based apps and scripts. Gramit intelligently aggregates and debounces output to ensure you don't get spammed with dozens of tiny messages.
2. External Stream Mode (-o / --output-stream): For complex TUI applications where raw terminal output is "noisy" (filled with borders, colors, and ANSI codes), you can instruct Gramit to "tail" a clean side-log file instead.

⌨️ Key Shortcuts & Modifiers

Interact with TUIs effortlessly using Telegram commands (use spaces between modifiers and keys):

• Special Keys: /enter, /esc, /t (Tab), /b (Backspace), /d (Delete).
• Arrow Keys: /up, /down, /left, /right.
• Modifiers:
  • /c <key> for Control (e.g., /c a for Ctrl+A).
  • /a <key> for Alt/Meta (e.g., /a x for Alt+X).
  • /s <key> for Shift.
• Combinations: /c /s a for Ctrl+Shift+A, /a /c /up for Alt+Ctrl+Up, etc.

🖥️ Native Terminal Experience

Gramit isn't just a blind pipe; it respects your terminal:

• Terminal Size Inheritance: Child processes automatically inherit the size of your host terminal on startup.
• Dynamic Resizing: Resize your local terminal window, and Gramit propagates the change to the child process instantly (SIGWINCH support).
• Local Mirroring: See the TUI running locally in your terminal while you interact with it remotely via Telegram.
• Robust Cleanup: When you exit, Gramit performs a full terminal restoration—clearing the screen, homing the cursor, disabling mouse tracking, and exiting alternate screen buffers. No more "broken" terminals!

🔒 Built-in Security

• Locked-down by Default: Only messages from your specific chat_id are processed.
• Credential Safety: Tokens are handled via environment variables or secured .env files.
• Rate Limiting: Protects your bot and machine from memory exhaustion and API flooding.

---

🌈 Magical Use Cases

Gramit isn't just a bridge; it's a superpower for your terminal. Here is how you can use it to transform your workflow.

👨‍🍳 The "Sous-Chef": Monitor Agents While Cooking

You've started a complex, long-running task—maybe a large codebase refactor with Gemini CLI or a 20-minute production build. You're hungry, but you don't want to stay tethered to your desk.

• The Workflow: Start the task with Gramit.
• The Freedom: Head to the kitchen. While your risotto simmers, your phone pings you with the agent's progress. If it hits a snag and asks for permission to delete a file, you just type y in Telegram and get back to your meal.

🚗 The Mobile Command Center: DevOps from the Back of an Uber

Production is down, and you're in a taxi. You don't want to wrestle with a mobile SSH client's tiny keyboard and lack of functional keys.

• The Workflow: gramit ssh production-server
• The Freedom: Use Gramit's shortcut commands. Need to check top? Just send the message. Need to exit a stuck process? /c c. Need to navigate a TUI logs viewer? /up and /down. You're a sysadmin with a thumb and a chat app.

🧠 The Second Brain: Telegram ⮕ Gemini ⮕ Obsidian

You're at the grocery store and have a breakthrough idea for your next project. You want it processed by an AI and saved directly into your Obsidian vault.

• The Workflow:

  gramit -o ~/Documents/Obsidian/Inbox.md gemini "Act as my research assistant. Append your thoughts to the log."
  

• The Freedom: Send your raw idea to the bot. Gemini processes it, expands on it, and Gramit "tails" that output directly into your Obsidian inbox file. By the time you get home, your "Second Brain" is already updated.

☕ The "Espresso" Build: Grab Coffee, Stay Informed

Some builds take just long enough to be annoying but not long enough to start a new task.

• The Workflow: gramit make build-all
• The Freedom: Walk to the breakroom. When the build finishes (or fails with a wall of red text), you'll see the exact error message on your phone. You can even run make clean remotely to reset before you walk back.

---

🛠️ Setup

1. Installation

   Install Gramit using your favorite Python package manager:

   Using pipx (Recommended for CLI tools):

   pipx install gramit
   

   Using uv:

   # Run without installing
   uvx gramit --help
   
   # Or install as a tool
   uv tool install gramit
   

2. Get a Telegram Bot Token

   • Talk to the @BotFather on Telegram.
   • Create a new bot and copy the token.

3. Set Environment Variables

   • Create a file named .env in your project root or your home directory.
   • Add your credentials (and secure the file: chmod 600 .env):

     GRAMIT_TELEGRAM_TOKEN="YOUR_TELEGRAM_TOKEN"
     GRAMIT_CHAT_ID="YOUR_CHAT_ID"
     

4. Find Your Chat ID If you don't know your ID, run:

   gramit --register
   

   Send any message to your bot, and it will reply with your ID.

---

📖 Usage Examples

Simple Command:

gramit ping 8.8.8.8

Interactive TUI with Side-Log:

# Start our built-in example chat app
gramit -o tui_echo.log python examples/tui_echo_with_log.py

---

🐧 Platform Support & Contributions

Gramit is currently only tested on Linux (bash).

Because it relies on native PTY features (os.forkpty, termios, fcntl), behavior on macOS or Windows (WSL) may vary.

Contributions are highly welcomed! If you've tested Gramit on other OSes or terminals and found bugs (or fixes), please open an issue or a PR.

📜 License

MIT License - see LICENSE for details.