dicnunz · JamesFincher · Apr 27, 2026 · Apr 27, 2026 · Apr 29, 2026 · Apr 29, 2026
diff --git a/.env.example b/.env.example
@@ -6,15 +6,40 @@ TELEGRAM_BOT_TOKEN=
 TELEGRAM_ALLOWED_USER_ID=
 TELEGRAM_ALLOWED_CHAT_ID=
 
+# Optional. Use only when your Python install or corporate proxy needs a
+# specific CA bundle to verify https://api.telegram.org.
+CODEX_RELAY_CA_FILE=
+
 # Telegram messages can make local edits through Codex. Defaults to your home folder.
 CODEX_RELAY_USER_NAME=
 CODEX_RELAY_ASSISTANT_NAME=Codex
 CODEX_RELAY_ASSISTANT_PERSONALITY=
+
+# Optional Gemini mobile assistant layer. Leave the key empty to disable it.
+# When configured, natural Telegram requests can be translated into relay actions,
+# and Codex replies can be polished for readability.
+# After install, you can also send /gemini key YOUR_GEMINI_API_KEY in Telegram.
+CODEX_RELAY_GEMINI_API_KEY=
+CODEX_RELAY_GEMINI_ENABLED=true
+CODEX_RELAY_GEMINI_MODEL=gemini-3.1-flash-lite-preview
+CODEX_RELAY_GEMINI_MAX_OUTPUT_TOKENS=4096
+CODEX_RELAY_GEMINI_NATURAL_COMMANDS=true
+CODEX_RELAY_GEMINI_POLISH=true
+CODEX_RELAY_GEMINI_TIMEOUT_SECONDS=20
+CODEX_RELAY_GEMINI_ERROR_NOTICES=true
+
+# Recovery, file transfer, and terminal controls work without Gemini.
+CODEX_RELAY_RECOVERY_TIMEOUT_SECONDS=1200
+CODEX_RELAY_TERMINAL_BUFFER_CHARS=20000
+CODEX_RELAY_TERMINAL_READ_LIMIT=4000
+CODEX_RELAY_ALLOW_SENSITIVE_FILE_TRANSFER=false
+
 CODEX_TELEGRAM_WORKDIR=
 CODEX_BIN=/Applications/Codex.app/Contents/Resources/codex
 CODEX_TELEGRAM_SANDBOX=danger-full-access
 CODEX_TELEGRAM_MODEL=gpt-5.5
-CODEX_TELEGRAM_REASONING_EFFORT=high
+# Default Codex thinking mode. Legacy CODEX_TELEGRAM_REASONING_EFFORT is still accepted.
+CODEX_TELEGRAM_THINKING_MODE=xhigh
 CODEX_TELEGRAM_SPEED=standard
 CODEX_TELEGRAM_REPLY_STYLE=brief
 CODEX_TELEGRAM_APPROVAL=never
@@ -23,5 +48,9 @@ CODEX_TELEGRAM_REPLY_TO_MESSAGES=false
 CODEX_TELEGRAM_REPLY_UNAUTHORIZED=false
 CODEX_TELEGRAM_ALLOW_GROUP_CHATS=false
 CODEX_TELEGRAM_TYPING_INTERVAL_SECONDS=4
+CODEX_TELEGRAM_POLL_TIMEOUT_SECONDS=25
+CODEX_TELEGRAM_POLL_HTTP_TIMEOUT_SECONDS=60
+CODEX_TELEGRAM_MAX_IMAGES_PER_MESSAGE=10
 CODEX_TELEGRAM_MAX_IMAGE_BYTES=20971520
+CODEX_TELEGRAM_MAX_FILE_BYTES=20971520
 CODEX_TELEGRAM_IMAGE_RETENTION_DAYS=7
diff --git a/PHONE_REMOTE.md b/PHONE_REMOTE.md
@@ -10,7 +10,7 @@ This is better than VNC when the goal is to command Codex, not manually drive a
 Phone prompt -> Telegram bot -> Mac LaunchAgent -> Codex CLI -> Telegram reply
 ```
 
-The default normal prompt path uses your configured Codex model, reasoning effort, and speed tier through the local Codex app CLI.
+The default normal prompt path uses your configured Codex model, active thinking mode, and speed tier through the local Codex app CLI.
 
 ## Prompts That Fit
 
@@ -36,11 +36,18 @@ Best prompts include a folder, a stopping point, and whether public actions are
 /tools
 /try
 /jobs
+/queue
+/activity
+/terminal
+/file README.md
+/recover
 /automations
 /history
+/gemini key YOUR_GEMINI_API_KEY
 
 /new school
 /cd Documents
+/think high
 check what class files look important this week
 
 /new portfolio
@@ -51,9 +58,10 @@ make the README feel pinned-worthy
 ## Response Timing
 
 - `/ping`, `/alive`, `/health`, `/policy`, `/screenshot`, `/status`, `/where`, `/list`, `/new`, and `/cd` should feel quick.
-- `/jobs`, `/cancel`, and `/history` should work while Codex is busy.
+- `/jobs`, `/cancel`, `/history`, `/activity`, `/queue`, `/terminal`, and `/file` should work while Codex is busy.
+- New normal requests can queue while the active thread is busy, including saved images. `/forget`, `/forgetphotos`, and `/queue next id` adjust that queue without Gemini.
 - Normal prompts wait for Codex to finish.
-- Normal prompts use your configured Codex model, reasoning effort, and speed tier.
+- Normal prompts use your configured Codex model, active thinking mode, and speed tier.
 - Image, browser, repo-editing, test-running, and desktop/app-control prompts can take tens of seconds or minutes. Desktop/app-control behavior depends on what your local Codex runtime exposes.
 - If the request is public or irreversible, ask Codex to draft and stop before posting, pushing, paying, deleting, or changing accounts.
 
@@ -70,6 +78,8 @@ make the README feel pinned-worthy
 
 This is a local Codex runtime, not a visible Codex Mac app thread. It can use the same signed-in Codex CLI/plugin setup, but it does not mirror the desktop chat UI.
 
-Telegram photos and image documents are saved in the private runtime state directory and attached to the next Codex prompt.
+Telegram photos, photo albums, and image documents are saved in the private runtime state directory and attached to the next Codex prompt or queued request.
+
+Gemini is optional. Slash commands are the primary control surface and work without Gemini; the mobile harness is powered by Flash 3.1 Lite and routes natural language to the same relay actions when configured. After the first install, `/gemini key YOUR_GEMINI_API_KEY` saves the key privately and reloads the relay without using the Mac screen.
 
 It is unofficial, uses your normal Codex/OpenAI account limits, and can only use tools exposed by the local Codex runtime on that Mac.
diff --git a/PRODUCT_QA.md b/PRODUCT_QA.md
@@ -40,7 +40,7 @@ The product is ready to show only when these are true:
 
 - Local LaunchAgent, not a hosted relay account.
 - Local Codex app CLI, not a separate agent backend.
-- Default model, reasoning effort, and speed tier are explicit in `.env.example`.
+- Default model, thinking mode, and speed tier are explicit in `.env.example`.
 - Telegram bot is allow-listed to one configured user/chat.
 - Runtime state lives under `~/Library/Application Support/CodexRelay`.
 - Runtime jobs expose `/jobs`, `/cancel`, and `/history` without logging prompts or responses.
@@ -55,12 +55,12 @@ Expected behavior:
 - `/ping`, `/alive`, `/health`, `/policy`, `/status`, `/where`, and thread commands should return quickly because they do not call Codex.
 - `/jobs`, `/cancel`, and `/history` should respond while a long Codex task is running.
 - Normal prompts show Telegram typing while Codex is running.
-- Normal prompts use the configured model, reasoning effort, and speed tier.
+- Normal prompts use the configured model, thinking mode, and speed tier.
 - `/screenshot` is a bridge command, not a Codex model call.
 - Final replies arrive only after the Codex CLI run finishes.
 - Longer waits are normal for image analysis, browser or desktop/app-control work, repo edits, tests, package installs, or prompts that require tool calls.
 - A task that exceeds `CODEX_TELEGRAM_TIMEOUT_SECONDS` stops with a timeout message.
-- `/history` stores only safe run receipts: status, latency, thread, job id, image count, folder basename, reasoning effort, and speed tier.
+- `/history` stores only safe run receipts: status, latency, thread, job id, image count, folder basename, thinking mode, and speed tier.
 
 Public answer:
 

diff --git a/README.md b/README.md
@@ -52,6 +52,43 @@ cd codex-relay
 
 The installer verifies the bot token, gives you a one-time `/start` code, allow-lists your private Telegram DM, installs the LaunchAgent, and runs `doctor.sh`.
 
+If token verification fails with `CERTIFICATE_VERIFY_FAILED`, rerun after fixing Python's CA bundle:
+
+```bash
+open "/Applications/Python 3.x/Install Certificates.command"
+```
+
+Codex Relay also retries Telegram HTTPS calls with the active Python CA path, `certifi` when installed, and common macOS/Homebrew CA bundles. On managed networks that use HTTPS inspection, set `CODEX_RELAY_CA_FILE=/path/to/your-ca.pem` in `.env` instead of disabling TLS verification.
+
+
+### Optional Gemini Assist
+
+After the first install, you can enable the Gemini mobile harness powered by Flash 3.1 Lite from Telegram, so the phone setup does not require opening the Mac:
+
+```text
+/gemini key YOUR_GEMINI_API_KEY
+```
+
+The relay saves the key privately, enables natural commands and answer polish, and reloads the setting in the running process. It also attempts to delete the Telegram message that contained the key. `/gemini on`, `/gemini off`, and `/gemini clear` can manage it later.
+
+You can still configure it manually in `.env`:
+
+```bash
+CODEX_RELAY_GEMINI_API_KEY=your-gemini-api-key
+CODEX_RELAY_GEMINI_MODEL=gemini-3.1-flash-lite-preview
+CODEX_RELAY_GEMINI_MAX_OUTPUT_TOKENS=4096
+CODEX_RELAY_GEMINI_NATURAL_COMMANDS=true
+CODEX_RELAY_GEMINI_POLISH=true
+```
+
+Then run:
+
+```bash
+./scripts/install_launch_agent.sh
+```
+
+With Gemini assist enabled, natural messages can map to relay actions before Codex runs. For example, `set my dir to /code/codex-relay and run a security audit` can set the active folder and start a Codex audit job. Codex still performs the repo work; Gemini only plans safe relay actions and optionally rewrites Codex's final answer to be easier to read on a phone. Gemini API key setup is handled by the relay before Codex sees the message; other messages that look like tokens, passwords, private keys, or `.env` content bypass Gemini. Use `/gemini` in Telegram to check the status.
+
 Then DM your bot:
 
 ```text
@@ -103,23 +140,36 @@ The demo proves the repo can run its smoke path without a Telegram token, local
 /jobs         running jobs and last run
 /cancel id    stop a running job
 /history      recent run receipts, no prompt/response logs
+/activity     running jobs, pending queue, terminals, safe history
 /automations  inspect Codex automations through Codex
 /tools        quick Codex tool probe
+/recover      run local relay recovery
 /try          useful first prompts
 /new name     new Codex thread
 /use name     switch threads
 /list         list threads
 /where        show active folder
 /cd path      set active folder
 /home         set folder to ~
+/think mode   set Codex thinking mode for this thread
+/queue        show or add pending requests
+/forget id    remove pending request
+/forgetphotos remove saved images from pending requests
+/terminal     persistent interactive terminal sessions
+/file path    send a local file back to Telegram
 /brief        terse replies for this thread
 /verbose      detailed replies for this thread
 /update       show local update command
+/gemini       optional mobile assist status/setup
 /reset        clear the current Codex session
 /ping         bridge check
 ```
 
-Normal messages go to the active thread. Captions on Telegram images become the prompt; image files are saved privately and attached to Codex.
+Normal messages go to the active thread. If the thread is busy, normal messages and downloaded image attachments are queued and start when the active job clears. Captions on Telegram images become the prompt; image files are saved privately and attached to Codex. Telegram photo albums are batched into one Codex job with up to `CODEX_TELEGRAM_MAX_IMAGES_PER_MESSAGE` images.
+
+Thinking modes are `low`, `medium`, `high`, and `xhigh`. `/think default` returns a thread to the configured default. Queue, image cleanup, file transfer, terminal sessions, recovery, and thinking-mode commands all work without Gemini. With Gemini assist enabled, natural messages can route to those same slash-command capabilities.
+
+Terminal sessions are PTY-backed and persist while the relay process is running: `/terminal open setup -- gh auth login`, `/terminal read setup`, `/terminal enter setup yes`, and `/terminal kill setup`. File transfer uses `/file path` from the active thread folder and blocks obvious secret/runtime files by default.
 
 ## Try It
 
@@ -133,7 +183,7 @@ https://github.com/dicnunz/codex-relay/issues/new?template=install-feedback.yml
 
 The ask is simple: install it, run `/alive`, `/health`, `/policy`, `/screenshot`, try one safe local task, and report what was confusing or broken. Do not paste bot tokens, `.env`, private screenshots, personal files, raw Codex transcripts, or unredacted logs.
 
-Normal messages use `CODEX_TELEGRAM_MODEL`, `CODEX_TELEGRAM_REASONING_EFFORT`, and `CODEX_TELEGRAM_SPEED` from `.env`. The sample config defaults to `gpt-5.5`, `high`, and `standard`; change those only if you intentionally want a different reasoning profile.
+Normal messages use `CODEX_TELEGRAM_MODEL`, `CODEX_TELEGRAM_THINKING_MODE`, and `CODEX_TELEGRAM_SPEED` from `.env`. The sample config defaults to `gpt-5.5`, `xhigh`, and `standard`; change those only if you intentionally want a different reasoning profile.
 
 `/status` shows the active model settings, last run status, and latency after Codex replies.