conexgram 0.1.0__tar.gz

conexgram-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alday Global
+
+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.

conexgram-0.1.0/PKG-INFO

@@ -0,0 +1,484 @@
+Metadata-Version: 2.4
+Name: conexgram
+Version: 0.1.0
+Summary: Run Codex CLI from Telegram
+Author: Alday Global
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aanoval/conexgram
+Project-URL: Repository, https://github.com/aanoval/conexgram
+Project-URL: Issues, https://github.com/aanoval/conexgram/issues
+Keywords: codex,telegram,cli,remote,gateway
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Conexgram
+
+[![CI](https://github.com/aanoval/conexgram/actions/workflows/ci.yml/badge.svg)](https://github.com/aanoval/conexgram/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/conexgram.svg)](https://pypi.org/project/conexgram/)
+[![Python](https://img.shields.io/pypi/pyversions/conexgram.svg)](https://pypi.org/project/conexgram/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Run Codex CLI from Telegram.
+
+Conexgram keeps coding sessions running on your own computer and lets you manage them from your phone.
+
+> Your code, credentials, and compute stay local.
+
+```text
+Telegram -> Conexgram -> Codex CLI -> your local workspace -> Telegram
+```
+
+## Install in 3 minutes
+
+Recommended:
+
+```bash
+curl -fsSL https://conexgram.com/install.sh | bash
+```
+
+Or with `pipx`:
+
+```bash
+pipx install conexgram
+conexgram setup
+conexgram doctor --fix
+conexgram install-service
+```
+
+Run in the foreground instead of installing a service:
+
+```bash
+conexgram run
+```
+
+Then send `/start` or `/settings` to your Telegram bot.
+
+If the bot says you are unauthorized, it will show your Telegram user ID and chat ID. Add one of those IDs to `~/.conexgram/config.json`.
+
+## Why Conexgram?
+
+Conexgram is useful when you want Codex to stay attached to your real local workspace while Telegram becomes the remote control surface. It is a good fit when you want to inspect a codebase, continue a session, check progress, or run supervised automation without opening your laptop.
+
+Good fits:
+
+- personal remote coding assistant for your workstation
+- lightweight DevOps helper for trusted private machines
+- Telegram-controlled Codex sessions for long-running work
+- local-first bridge for future multi-agent workflows
+
+## Features
+
+- Telegram bot -> Codex CLI bridge
+- Persistent Codex sessions per chat or per user
+- Session controls like `/new`, `/status`, `/sessions`, `/switch`, `/workspace`
+- Runtime controls like `/model`, `/reasoning`, `/mode`, `/preset`, `/fast`
+- Progress UX like `/typing`, `/progress`, `/silent`, `/tail`
+- Telegram file upload into the active workspace
+- Optional local file send-back with `/sendfile`
+- Works in the foreground or as an auto-start service on macOS, Linux, or Windows
+- No third-party Python dependencies
+- Small modular Python internals with room for future agent routing
+
+## How it works
+
+```text
+Telegram message
+  -> Telegram Bot API
+  -> Conexgram on your machine
+  -> Codex CLI
+  -> final response
+  -> Telegram reply
+```
+
+## What you can do from Telegram
+
+- Start and resume Codex sessions
+- Switch between safe, work, fast, power, and Computer Access presets
+- Change model and reasoning effort per session
+- Upload files into the active workspace
+- Send local files back to Telegram
+- Watch long-running tasks with typing and progress indicators
+- Stop a running Codex turn from your phone
+
+Conexgram keeps two layers of state:
+
+- **Gateway session**: local session record managed by Conexgram
+- **Codex thread**: actual Codex CLI thread id used for resume/continuation
+
+## Security model
+
+Conexgram is remote-control software. Treat it like operator tooling, not a public chatbot.
+
+- Your code, credentials, and compute stay on your own machine
+- Telegram access should be restricted with `allowed_user_ids` or `allowed_chat_ids`
+- Workspace mode is the recommended default
+- Full access and Computer Access require explicit local opt-in
+
+Read more in [docs/security.md](docs/security.md).
+
+## Requirements
+
+- Python 3.11+
+- `codex` CLI installed and authenticated
+- A Telegram bot token from BotFather
+- Your Telegram user id or allowed chat id
+
+Quick check:
+
+```bash
+codex --version
+codex exec --help
+python3 --version
+```
+
+## Source checkout
+
+If you want to run from a source clone:
+
+```bash
+git clone https://github.com/aanoval/conexgram.git
+cd conexgram
+python3 -m conexgram setup
+python3 -m conexgram doctor --fix
+python3 -m conexgram run
+```
+
+## Install from source
+
+```bash
+git clone https://github.com/aanoval/conexgram.git
+cd conexgram
+python3 -m conexgram init-config
+```
+
+For a guided setup:
+
+```bash
+python3 -m conexgram setup
+```
+
+Or edit config manually:
+
+```bash
+nano ~/.conexgram/config.json
+```
+
+Then validate:
+
+```bash
+python3 -m conexgram doctor
+```
+
+Run:
+
+```bash
+python3 -m conexgram run
+```
+
+You can also use the entry script:
+
+```bash
+python3 gateway.py run
+```
+
+## One-tap auto-start install
+
+Create and edit `~/.conexgram/config.json` first, then run the installer for your platform.
+If the config does not exist yet, `./scripts/install.sh` starts the guided setup first.
+
+macOS or Linux:
+
+```bash
+./scripts/install.sh
+```
+
+macOS direct installer:
+
+```bash
+./scripts/install_launch_agent.sh
+```
+
+Linux user systemd installer:
+
+```bash
+./scripts/install_linux_systemd.sh
+```
+
+Windows PowerShell:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1
+```
+
+The installers register Conexgram to launch automatically at login and start it immediately.
+
+If Conexgram was installed with `pipx`, you can also use:
+
+```bash
+conexgram install-service
+conexgram uninstall-service
+```
+
+## Example config
+
+Key fields:
+
+- `telegram.bot_token`
+- `telegram.allowed_user_ids`
+- `telegram.allowed_chat_ids`
+- `codex.binary`
+- `codex.default_working_dir`
+- `codex.additional_writable_dirs`
+- `codex.workspace_roots`
+- `codex.model`
+- `codex.reasoning_effort` (optional; leave empty to use the Codex default)
+- `codex.mode`
+- `codex.full_access`
+- `codex.allow_runtime_full_access`
+- `progress.typing_indicator`
+- `progress.progress_messages`
+
+Troubleshooting: see `docs/troubleshooting.md`.
+
+Generate a fresh config:
+
+```bash
+python3 -m conexgram example-config
+```
+
+## Commands
+
+Common commands first:
+
+- `/new [working_dir]` — start a fresh Codex session
+- `/status` — show the active session
+- `/sessions` — list recent sessions
+- `/workspace [list|switch <path_or_number>|<path>]` — show or set allowed workspace
+- `/settings` — show a friendly settings panel
+- `/tail` — show the latest Codex output for this session
+- `/stop` — stop the running Codex process
+
+Full command set:
+
+- `/new [working_dir]` — start a fresh Codex session
+- `/status` — show the active session
+- `/sessions` — list recent sessions
+- `/switch <number_or_id>` — switch active session
+- `/cwd [path]` — show or set working directory before Codex thread starts
+- `/workspace [list|switch <path_or_number>|<path>]` — show or set allowed workspace
+- `/model [name|default]` — show or set model for this session
+- `/models` — list configured model presets
+- `/reasoning default|low|medium|high|xhigh` — set reasoning effort, or reset to the Codex default
+- `/mode safe|workspace|full|<preset>` — set execution mode or preset
+- `/preset list|safe|work|fast|power|computer` — apply a common setup
+- `/fast on|off` — toggle fast mode
+- `/fullaccess status|on|off` — inspect or toggle full access if config allows it
+- `/computer status|on|off` — user-friendly alias for full access
+- `/settings` — show a friendly settings panel
+- `/permissions` — show effective local access settings
+- `/typing status|on|off|default` — control typing indicator for this session
+- `/progress status|on|off|default` — control long-running progress messages
+- `/silent status|on|off|default` — quickly silence or restore progress UX
+- `/rename <title>` — rename active session
+- `/summary` — show active session summary
+- `/reset` — start a fresh default session
+- `/logs [gateway|launchd]` — send a local log file
+- `/tail` — show the latest Codex output for this session
+- `/doctor` — run setup checks from Telegram
+- `/version` — show Conexgram, Python, and Codex details
+- `/config` — show config summary
+- `/quota` — show Codex usage and rate-limit status
+- `/codexstatus` — alias for `/quota`
+- `/codex <args>` — run a native Codex CLI command, for example `/codex --version`
+- `/sendfile <path> [caption]` — send a local file to Telegram
+- `/stop` — stop the running Codex process
+- `/help` — show help
+
+Any non-command text is forwarded to the active Codex session.
+
+## Progress UX
+
+Conexgram can show Telegram's `typing...` indicator while Codex is running. Telegram only displays each typing action briefly, so Conexgram refreshes it every few seconds.
+
+Default:
+
+```json
+{
+  "progress": {
+    "typing_indicator": true,
+    "typing_interval_seconds": 4,
+    "progress_messages": true,
+    "progress_interval_seconds": 60
+  }
+}
+```
+
+Set both values to `false` to keep the bot silent until Codex returns the final answer:
+
+```json
+{
+  "progress": {
+    "typing_indicator": false,
+    "progress_messages": false
+  }
+}
+```
+
+Allowed Telegram users can also change progress UX per session:
+
+```text
+/typing off
+/progress off
+/silent on
+/silent default
+```
+
+## Security notes
+
+Conexgram can expose meaningful access to your local machine through Codex CLI.
+
+Recommended defaults:
+
+- keep the bot private
+- use `allowed_user_ids` and/or `allowed_chat_ids`
+- leave `full_access` as `false` unless you explicitly want unrestricted Codex execution
+- leave `allow_runtime_full_access` as `false` unless you want Telegram users to toggle full access
+- set `workspace_roots` so `/workspace`, `/cwd`, and `/sendfile` stay inside known folders
+- run it on a dedicated machine or workspace if possible
+
+When `codex.full_access=true`, Conexgram adds:
+
+```bash
+--dangerously-bypass-approvals-and-sandbox
+```
+
+Only enable that if you understand the risk.
+
+### Runtime full access from Telegram
+
+Telegram users cannot enable full access by default. The machine owner must opt in locally first:
+
+```json
+{
+  "codex": {
+    "full_access": false,
+    "allow_runtime_full_access": true
+  }
+}
+```
+
+After restarting Conexgram, allowed Telegram users can toggle it:
+
+```text
+/fullaccess on
+/fullaccess off
+/fullaccess status
+/mode full
+/mode safe
+```
+
+Keep `allow_runtime_full_access=false` if the Telegram bot should never be able to switch Codex into unrestricted local execution.
+
+For non-technical users, `/computer` is the friendly alias:
+
+```text
+/computer status
+/computer on
+/computer off
+/confirm computer
+```
+
+Common presets:
+
+```text
+/preset safe
+/preset work
+/preset fast
+/preset power
+/preset computer
+```
+
+`/preset computer` also requires `allow_runtime_full_access=true`.
+
+Conexgram is unofficial and is not affiliated with OpenAI.
+
+## Auto-start services
+
+macOS uses a LaunchAgent:
+
+```bash
+./scripts/install_launch_agent.sh
+```
+
+Stop macOS:
+
+```bash
+launchctl bootout "gui/$(id -u)/com.conexgram.agent"
+```
+
+Linux uses a user systemd service:
+
+```bash
+systemctl --user status conexgram.service
+systemctl --user disable --now conexgram.service
+```
+
+Windows uses a Scheduled Task:
+
+```powershell
+Get-ScheduledTask -TaskName Conexgram
+Stop-ScheduledTask -TaskName Conexgram
+```
+
+Logs:
+
+```text
+~/.conexgram/gateway.log
+~/.conexgram/logs/
+```
+
+## Internal structure
+
+Key modules:
+
+- `conexgram/app.py` — gateway loop and Telegram update processing
+- `conexgram/commands.py` — Telegram slash commands
+- `conexgram/codex_runner.py` — Codex CLI execution and JSON event parsing
+- `conexgram/progress.py` — typing indicator and long-running progress messages
+- `conexgram/session_store.py` — local session persistence
+- `conexgram/agents.py` — future multi-agent profile primitives
+
+## Packaging
+
+For users:
+
+```bash
+pipx install conexgram
+```
+
+For local editable development:
+
+```bash
+pip install -e .
+conexgram --help
+```
+
+Release details: see `docs/pypi-release.md`.
+Curl installer details: see `docs/curl-install.md`.
+
+## Project status
+
+Conexgram is intentionally small and focused. The goal is a clean, understandable bridge for remote Codex usage over Telegram — not a full remote agent platform.