heyCodex

Use Telegram as a remote control surface for local Codex Desktop / Codex CLI workspaces.

heyCodex runs a small Telegram bot on your machine. Messages from allowed Telegram users are forwarded to local codex app-server; streaming Codex replies are edited back into Telegram. It is designed for personal remote access to your own development or research workspaces.

Status

This project is early but usable:

• Telegram long polling, no public webhook required.
• Local Codex app-server transport over stdio by default.
• Workspace allowlist with realpath checks.
• Per-chat in-memory locking to avoid concurrent turns.
• Automatic resume of the latest local Codex session for the selected workspace.
• Optional full-auto approval mode.
• HTTP(S) network proxy support for Telegram Bot API access.

Codex Desktop may not live-refresh turns written by an independent app-server process. The conversation is still written to ~/.codex/sessions; reopening the thread in Codex Desktop usually shows the persisted history.

Requirements

• macOS or Linux with Node.js 22 or newer.
• Codex CLI installed and logged in. If you use Codex Desktop on macOS, the CLI is usually at:

/Applications/Codex.app/Contents/Resources/codex

• A Telegram bot token from BotFather.
• Your Telegram numeric user id.

Quick Start

git clone git@github.com:0xfakeSpike/heyCodex.git
cd heyCodex
npm install
npm run build

Or install from npm:

npm install -g @fakespike233/heycodex

Create a config file:

cp .env.example .env

Set only the required values:

TELEGRAM_BOT_TOKEN=123456:your-token
ALLOWED_TELEGRAM_USERS=123456789

Start a workspace:

PATH="/Applications/Codex.app/Contents/Resources:$PATH" \
npm start -- -C /Users/you/project

If installed from npm, use the CLI directly:

PATH="/Applications/Codex.app/Contents/Resources:$PATH" \
heycodex -C /Users/you/project

Common startup commands after npm install:

# Normal mode
heycodex -C /Users/you/project

# Full-auto mode
heycodex --full-auto -C /Users/you/project

# Fast mode: do not resume a long Desktop session
heycodex --full-auto --no-resume -C /Users/you/project

If your network cannot reach api.telegram.org directly, set a Telegram network proxy with HTTPS_PROXY / HTTP_PROXY:

HTTPS_PROXY=http://127.0.0.1:15236 \
HTTP_PROXY=http://127.0.0.1:15236 \
PATH="/Applications/Codex.app/Contents/Resources:$PATH" \
npm start -- -C /Users/you/project

Then send /status to your Telegram bot.

Common Aliases

Normal mode, approvals are declined unless Codex can proceed without them:

alias heycodexLocal='cd /path/to/heyCodex && PATH="/Applications/Codex.app/Contents/Resources:$PATH" npm start -- -C /path/to/workspace'

Full-auto mode, closer to codex --full-auto:

alias heycodexFull='cd /path/to/heyCodex && PATH="/Applications/Codex.app/Contents/Resources:$PATH" npm start -- --full-auto -C /path/to/workspace'

With a Telegram network proxy:

alias heycodexProxy='cd /path/to/heyCodex && HTTPS_PROXY=http://127.0.0.1:15236 HTTP_PROXY=http://127.0.0.1:15236 PATH="/Applications/Codex.app/Contents/Resources:$PATH" npm start -- --full-auto -C /path/to/workspace'

This proxy is only for Telegram Bot API requests. It is unrelated to --proxy / CODEX_TRANSPORT=proxy.

Telegram Commands

Command	Description
/ask <text> or plain text	Start a Codex turn in the current thread.
/status	Show cwd, thread id, lock state, and active turn id.
/cwd <absolute-path>	Switch workspace, subject to WORKSPACE_ALLOWLIST.
/new	Force the next message to create a new Codex thread.
/stop	Interrupt the active turn when a turn id is known.
/help	Show bot help.

Configuration

Only these are required:

Variable	Description
TELEGRAM_BOT_TOKEN	Token from BotFather.
ALLOWED_TELEGRAM_USERS	Comma-separated Telegram user ids allowed to use the bot.

Useful optional values:

Variable / flag	Default	Description
-C, --cwd, DEFAULT_CWD	process cwd	Workspace used for the chat.
WORKSPACE_ALLOWLIST	DEFAULT_CWD	Comma-separated roots allowed for /cwd.
--full-auto, CODEX_AUTO_APPROVE=true	false	Auto-accept command/file/permission approvals.
--no-resume, CODEX_RESUME_LATEST=false	true	Disable automatic resume of the latest local Codex session. Use this when old Desktop sessions are large and simple Telegram turns feel slow.
CODEX_TRANSPORT	stdio	stdio, proxy, or ws.
CODEX_WS_URL	ws://127.0.0.1:4500	WebSocket app-server URL when using ws.
HTTPS_PROXY, HTTP_PROXY	unset	Network proxy for Telegram Bot API requests. Lowercase variants are also supported.
TURN_TIMEOUT_MS	1800000	Turn timeout in milliseconds.

The app supports three Codex app-server transports:

Transport	Use case
stdio	Default. Starts an independent local codex app-server. This is the most reliable mode.
ws	Connects to a manually started app-server, for example codex app-server --listen ws://127.0.0.1:4500.
proxy	Runs codex app-server proxy and connects to a Codex app-server control socket. This is experimental and only works if your Codex build exposes that socket. It is not an HTTP/VPN proxy.

Performance Notes

By default, heyCodex resumes the newest local Codex session for the selected workspace. This preserves Desktop context, but very long sessions can make even simple Telegram messages slow because Codex has to process the recovered conversation context.

For a fast remote-control chat, start with --no-resume or set CODEX_RESUME_LATEST=false. Use /new inside Telegram to start a fresh thread during the current bridge process.

Security Model

This project intentionally controls local Codex from Telegram. Treat the bot token and allowed-user list as sensitive.

• Never expose Codex app-server WebSocket to the public internet.
• Keep ALLOWED_TELEGRAM_USERS narrow.
• Keep WORKSPACE_ALLOWLIST narrow.
• Avoid --full-auto for workspaces where unreviewed command execution or file edits are unacceptable.
• The bridge stores active state in memory; Codex conversation history is stored by Codex under ~/.codex/sessions.

Development

npm install
npm run build
npm run dev -- -C /Users/you/project

The project is TypeScript-first because Codex app-server can generate TypeScript protocol bindings. The app-server protocol is still experimental; check compatibility with:

codex app-server generate-ts --out /tmp/codex-appserver-ts

License

MIT