gramit 0.2.0__tar.gz

gramit-0.2.0/.github/workflows/release.yaml

@@ -0,0 +1,56 @@
+name: Release Pipeline
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups --no-editable
+
+      - name: Run format check
+        run: uv run ruff check
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=gramit --cov-report=xml --cov-report=term
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  publish-pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}

gramit-0.2.0/.github/workflows/tests.yaml

@@ -0,0 +1,32 @@
+name: Run Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups --no-editable
+
+      - name: Run format check
+        run: uv run ruff check
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=gramit --cov-report=xml --cov-report=term

gramit-0.2.0/.gitignore

@@ -0,0 +1,176 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python
+# Edit at https://www.toptal.com/developers/gitignore?templates=python
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# End of https://www.toptal.com/developers/gitignore/api/python

gramit-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

gramit-0.2.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v0.1.2]
+
+### Security
+- Implemented rate-limiting and output trimming in `OutputRouter` and `AsyncDebouncer` to prevent memory exhaustion and respect Telegram's message size limits.
+- Restricted local `.env` file permissions to owner-only (`600`) to protect sensitive tokens.
+- Added a prominent security warning to `README.md` regarding the risks of remote command execution.
+
+### Added
+- Added detailed installation instructions for `pip`, `pipx`, and `uv` to `README.md`.
+- Added project descriptors (keywords, classifiers, and URLs) to `pyproject.toml` for better metadata and discoverability.
+
+### Fixed
+- Corrected a missing f-string in `cli.py` logging.
+
+## [v0.0.1]
+
+### Fixed
+- Ensured `Ctrl+C` triggers graceful shutdown by restructuring `try...except asyncio.CancelledError` block within `async with application:` in `cli.py`.
+- Resolved `UnboundLocalError` for `shutdown_event` by moving its initialization to an earlier point in `cli.py`.
+- Implemented graceful shutdown for `Ctrl+C` and `/quit` command by using `asyncio.Event` to signal shutdown and ensuring all components are properly terminated.
+- Replaced `application.run_until_disconnected()` with `async with application:` and `await asyncio.Future()` for correct asynchronous Telegram bot lifecycle management in `cli.py`.
+- Reverted temporary debugging changes in `cli.py` and `telegram.py` to restore intended application flow.
+- Corrected `SyntaxError` in `src/gramit/telegram.py` related to an unmatched parenthesis.
+
+### Added
+- Initial and goodbye messages sent to Telegram upon gramit startup/shutdown.
+- `/quit` Telegram command to gracefully terminate the orchestrated process.
+- `examples/reverse_echo.py` script for interactive testing.
+- Console script `gramit` for easier execution.
+- `--register` mode to easily find a user's chat ID.
+- Support for `GRAMIT_CHAT_ID` environment variable as an alternative to `--chat-id`.
+- Main application entrypoint (`cli.py`) to integrate all components.
+- `InputRouter` to handle and authorize incoming Telegram messages.
+- `OutputRouter` to process and send output in line-buffered mode.
+- `AsyncDebouncer` utility to batch items after a period of inactivity.
+- I/O handling (`read`/`write`) to the `Orchestrator`.
+- `Orchestrator` class to manage child processes in a pseudo-terminal (PTY).
+- Initial project structure with `uv`, `pytest`, and core directories.
+- `GEMINI.md` with project development guidelines.
+- `DESIGN.md` v2.1, a robust architectural plan for the application.
+- `ROADMAP.md` detailing the phased implementation plan.
+- `CHANGELOG.md` to track notable changes.
+- `journal/` directory for detailed daily progress logs.
+
+### Changed
+- Overhauled the initial system design to address critical security, dependency, and usability issues.

gramit-0.2.0/DESIGN.md

@@ -0,0 +1,81 @@
+# Gramit: Architectural & System Design Document (v2.1)
+
+## 1. System Overview & Design Principles
+
+Gramit is a secure, self-contained Python orchestrator that bridges a local, command-line application with a remote Telegram interface. It allows a single, authorized user to control and monitor any CLI process from their Telegram chat.
+
+This design adheres to the following principles:
+
+*   **Security First:** The system is locked down by default. It requires explicit user authorization and uses secure methods for handling credentials.
+*   **Zero External Dependencies:** The application is a pure Python tool and does not require external binaries like `tmux`. This enhances portability and reduces complexity.
+*   **Remote-First Interaction:** The primary interface is Telegram. Simultaneous local terminal interaction is not supported, which eliminates input race conditions and simplifies the design.
+*   **Intelligent TUI Parsing:** It is designed to extract meaningful text from Terminal User Interfaces (TUIs), filtering out UI "chrome" like borders and control panels.
+
+## 2. Core Architecture
+
+Gramit is built on `asyncio`. When launched, it starts a main orchestrator that runs the target command in a pseudo-terminal (PTY) and manages three core asynchronous components.
+
+![Gramit Architecture Diagram](https://i.imgur.com/9A7SO88.png)
+
+### 2.1. The PTY Orchestrator
+This component replaces the `tmux` dependency.
+
+*   **Initialization:** On startup, the orchestrator uses `os.forkpty()` to create a new child process running inside a pseudo-terminal. This correctly allocates a PTY, ensuring that interactive applications (including TUIs) behave as expected.
+*   **Lifecycle Management:** The orchestrator owns the child process and the master file descriptor for the PTY. It is responsible for gracefully shutting down all components when the child process exits.
+
+### 2.2. The Input Router (Telegram → PTY)
+This component handles incoming commands from Telegram.
+
+*   **Authorization:** It uses a Telegram bot library (e.g., `python-telegram-bot`) to listen for messages. It will **only** process messages from a single, pre-authorized `chat_id` provided at startup. All other messages are discarded.
+*   **Injection:** When an authorized message is received, its text content is written directly to the master PTY file descriptor, which passes it to the `stdin` of the running child process.
+
+### 2.3. The Output Router (PTY → Telegram)
+This component intelligently captures, processes, and transmits output from the application back to the user. It operates in one of two modes.
+
+#### 2.3.1. TUI Mode (Default)
+This mode is designed for interactive applications like `htop`, `vim`, or other curses-based programs.
+
+1.  **Virtual Screen:** The raw byte stream from the master PTY (which includes ANSI escape codes) is fed into an in-memory terminal emulator powered by the `pyte` library.
+2.  **Stateful Rendering:** The `pyte` screen object processes the escape codes and maintains a complete, 2D grid representing the terminal's current visual state.
+3.  **Snapshotting:** A debounced `asyncio` task runs at a configurable interval (e.g., every 2 seconds). In each interval, it dumps the current text content of the `pyte` screen.
+4.  **Heuristic Filtering (Content Extraction):** Before transmission, the raw text snapshot is passed through a filtering pipeline to remove common TUI "chrome." This is a best-effort attempt to extract semantic content and includes:
+    *   Removing lines that primarily consist of box-drawing characters (e.g., `│`, `─`, `┌`).
+    *   Stripping common control and menu indicators (e.g., lines containing patterns like "F1 Help", "F10 Quit").
+    *   Trimming leading/trailing whitespace from each line and removing empty lines from the top and bottom of the snapshot.
+5.  **Transmission:** The **cleaned** text snapshot is wrapped in a Telegram markdown code block and sent using `editMessageText` to update a single, persistent "screen" message. If the snapshot exceeds Telegram's 4096-character limit, it is truncated with a warning.
+
+#### 2.3.2. Line Mode (`--line-mode`)
+This mode is for simple, non-interactive applications that produce a stream of log-like output.
+
+1.  **Line Buffering:** The raw output from the PTY is decoded and buffered line by line.
+2.  **Debounced Flush:** The debounced task flushes this buffer of lines.
+3.  **Transmission:** The collected lines are joined and sent as one or more *new messages* using `sendMessage`. The router automatically handles splitting content across multiple messages if it exceeds the character limit.
+
+## 3. Security Model
+
+The security of the system is paramount and is addressed through two key mechanisms.
+
+### 3.1. Credential Management
+The Telegram Bot Token is treated as a sensitive secret.
+
+*   **Environment Variable:** The token **must** be provided via an environment variable (`GRAMIT_TELEGRAM_TOKEN`).
+*   **`.env` Support:** For ease of local development, the application will automatically load this variable from a `.env` file in the project root if it exists (using `python-dotenv`).
+*   The insecure `-t` command-line argument has been removed.
+
+### 3.2. Access Control
+Access to the bot is strictly controlled.
+
+*   **Required `chat_id`:** The application requires a `--chat-id <ID>` argument on startup. This locks the bot to a specific user or group.
+*   **Helper Utility:** A small utility script will be provided (`gramit-get-chat-id`) to help users easily find their `chat_id`.
+
+## 4. Summary of Countermeasures
+
+This revised design directly addresses the challenges of the initial proposal:
+
+| Issue | Countermeasure |
+| :--- | :--- |
+| **TUI Incompatibility** | Replaced `tail -f` approach with a `pyte`-based virtual screen and added a heuristic filtering layer to extract meaningful content. |
+| **`tmux` Dependency** | Eliminated `tmux` entirely by using Python's native `os.forkpty()` to manage the pseudo-terminal directly. |
+| **Input Race Conditions** | Removed the "local attach" feature. By making Telegram the sole source of input, race conditions are impossible. |
+| **Output Limits** | Implemented two distinct output modes (TUI and Line) with intelligent handling of message edits, new messages, and character limits. |
+| **Security Flaws** | Enforced secure token handling via environment variables and mandated `chat_id` authorization to lock down the bot. |

gramit-0.2.0/GEMINI.md

@@ -0,0 +1,51 @@
+# Gemini Project Guidelines
+
+This document outlines the conventions and procedures to be followed by the Gemini agent for this project.
+
+## Core Workflow
+
+A strict, iterative, and well-documented workflow must be followed for all projects. This ensures the project history is clear and documentation stays current with the code.
+
+The following files are central to this workflow and must be kept in sync with all development activities:
+
+- **`ROADMAP.md`**: Outlines the high-level development plan. It should be updated as major phases or tasks are completed.
+- **`CHANGELOG.md`**: Contains a user-facing summary of notable changes. An entry should be added for every significant feature, fix, or improvement.
+- **`journal/`**: A directory containing detailed, chronological logs of all actions, thoughts, and decisions made during development, with one file per day (e.g., `journal/YYYY-MM-DD.md`).
+
+The development process is as follows:
+
+1.  **Iterate Step-by-Step**: Work in small, incremental steps, following the project's specific development methodology.
+2.  **Document as You Go**: After each step, immediately update all relevant documentation (`ROADMAP.md`, `CHANGELOG.md`, `journal/`).
+3.  **Commit Often**: After each meaningful and atomic change (including its documentation), create a commit with a clear message.
+
+---
+
+## Project-Specific Guidelines
+
+This section details the specific tooling and methodologies for the **gramit** project.
+
+### Project Overview
+This is a Python 3.12 project.
+
+### Environment and Dependency Management
+- **Tooling:** We will use `uv` for all environment and package management tasks.
+- **Running commands:** Any scripts or commands should be executed within the `uv` environment using `uv run`. For example: `uv run python my_script.py` or `uv run pytest`.
+- **Adding dependencies:** Dependencies must be added using `uv add <package_name>`. For dev-only dependencies, use `uv add --dev <package_name>`.
+- **Dependency file:** Do not manually edit the `dependencies` or `dev-dependencies` sections in `pyproject.toml`.
+
+### Development Methodology
+- **Test-Driven Development (TDD):** We will strictly follow TDD.
+    1.  Write a failing test that clearly defines the desired functionality.
+    2.  Run the test to confirm that it fails as expected.
+    3.  Write the minimum amount of code necessary to make the test pass.
+    4.  Run all tests to confirm they all pass.
+    5.  Refactor the code as needed, ensuring tests continue to pass.
+
+---
+
+## General Coding Standards
+
+### Documentation and Commenting
+- **Public Functions:** All public functions must have clear and comprehensive docstrings explaining their purpose, arguments, and return values.
+- **Inline Comments:** Avoid unnecessary inline comments. Code should be as self-documenting as possible.
+- **Comment Style:** When comments are necessary, they should explain the *why* (the logic or reasoning) behind a piece of code, not the *what* (the implementation details).

gramit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Piad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gramit-0.2.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: gramit
+Version: 0.2.0
+Summary: A tool to bridge local CLI applications with a remote Telegram interface.
+Project-URL: Homepage, https://github.com/apiad/gramit
+Project-URL: Repository, https://github.com/apiad/gramit
+Project-URL: Issues, https://github.com/apiad/gramit/issues
+Project-URL: Changelog, https://github.com/apiad/gramit/blob/main/CHANGELOG.md
+Author-email: Alejandro Piad <alepiad@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: bridge,cli,remote-control,telegram,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: pyte>=0.8.2
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: python-telegram-bot>=22.6
+Description-Content-Type: text/markdown
+
+# Gramit
+
+[![Run Tests](https://github.com/apiad/gramit/actions/workflows/tests.yaml/badge.svg)](https://github.com/apiad/gramit/actions/workflows/tests.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+
+> [!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.
+
+Gramit bridges a local CLI application with a remote Telegram interface. It allows you to run any long-running command on your machine and interact with it from anywhere using Telegram. While designed to be generic for any CLI, it's particularly useful for interactive AI CLIs like **Gemini CLI**, **Claude Code**, or similar tools where you want to maintain a persistent session and interact remotely.
+
+## How it Works
+
+Gramit acts as a conduit between your local command-line application and your Telegram bot.
+-   **Input Redirection:** Any message you send to your Telegram bot is piped directly to the `stdin` of the running local command.
+-   **Output Capture:** All `stdout` from your local command is captured and sent back to you as a Telegram message.
+-   **Session Management:** It maintains a persistent session, allowing for continuous interaction with your CLI application.
+
+## Setup
+
+1.  **Installation**
+
+    You can install Gramit using your favorite Python package manager:
+
+    **Using `pip`:**
+    ```sh
+    pip install gramit
+    ```
+
+    **Using `pipx` (Recommended for CLI tools):**
+    ```sh
+    pipx install gramit
+    ```
+
+    **Using `uv`:**
+    ```sh
+    # 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](https://t.me/BotFather) on Telegram.
+    - Create a new bot and copy the token it gives you.
+
+3.  **Set Environment Variables**
+    - Create a file named `.env` in the project root.
+    - Add the following line to it, replacing `YOUR_TOKEN_HERE` with the token you just got:
+      ```
+      GRAMIT_TELEGRAM_TOKEN="YOUR_TOKEN_HERE"
+      ```
+    - You can also optionally add your Chat ID to this file (see step 4):
+      ```
+      GRAMIT_CHAT_ID="YOUR_CHAT_ID_HERE"
+      ```
+
+4.  **Find Your Chat ID**
+    - The easiest way to find your chat ID is to use Gramit's built-in registration mode. Run the following command:
+      ```sh
+      gramit --register
+      ```
+    - Now, send any message to your bot on Telegram. Gramit will print your Chat ID to the console and also reply with it.
+    - Once you have your ID, you can stop the command (`Ctrl_C`).
+
+## Usage
+
+Run `gramit` with your command. If you have not set `GRAMIT_CHAT_ID` in your `.env` file, you must also provide the `--chat-id` argument.
+
+**Basic Example:**
+```sh
+# If GRAMIT_CHAT_ID is set in .env
+gramit ping 8.8.8.8
+
+# If GRAMIT_CHAT_ID is NOT set
+gramit --chat-id YOUR_CHAT_ID ping 8.8.8.8
+```
+
+- Any text you send to your bot on Telegram will be piped to the `stdin` of the running command.
+- Any `stdout` from the command will be sent back to you as a Telegram message.
+
+**Interactive Example (Reverse Echo):**
+```sh
+gramit python examples/reverse_echo.py
+```
+Then, send messages to your bot on Telegram. It will echo them back in reverse.
+
+**Features:**
+- Upon starting, Gramit sends an initial message to Telegram indicating the command being run.
+- When the orchestrated process ends, a "goodbye" message is sent to Telegram.
+- Send `/quit` to your bot to gracefully terminate the running command from Telegram.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributions
+
+Contributions are welcome! If you have suggestions for improvements, new features, or bug fixes, please open an issue or submit a pull request.