Codex Anywhere

Codex Anywhere is a Telegram-native client for codex, so you can use Codex anywhere, anytime with session continuity, native Codex commands, featured /goal support, and first-class Oh-My-Codex workflows. Install it as a background service to operate native Codex from Telegram at your fingertips anywhere, anytime, 24/7, with no extra API key.

Prerequisites

• codex installed and signed in
• A Telegram bot token from @BotFather

Quick Start

1. Install

npm install -g codex-anywhere

Check the installed CLI version with:

codex-anywhere --version

2. Create a Telegram bot

Open @BotFather in Telegram, send /newbot, and follow the prompts. Copy the bot token for the next step.

3. Connect

codex-anywhere connect

Telegram bot token (from BotFather): <paste your token here>
Workspace path for Codex tasks [/current/dir]:  ← press Enter to accept

The workspace defaults to the folder where you run connect.

Add another Telegram bot

codex-anywhere add-bot

Use this when you want another bot pointed at another workspace.

Use a Codex config profile for a bot

Codex Anywhere starts its own codex app-server, which always reads the base $CODEX_HOME/config.toml. To run a bot against a different provider — for example a $CODEX_HOME/deepseek.config.toml profile you normally load with codex --profile deepseek — set codexProfile on that bot in config.json:

{
  "id": "deepseek",
  "label": "DeepSeek",
  "codexProfile": "deepseek"
}

codex app-server does not accept --profile, so Codex Anywhere replays the model settings from $CODEX_HOME/<profile>.config.toml (model, model_provider, model_catalog_json, reasoning effort, and the matching model_providers.<name> block) as -c overrides. Everything else keeps coming from the base config.

Switch profiles and browse every session

/continue and /resume list sessions from every provider Codex Anywhere can find — the base $CODEX_HOME/config.toml plus each $CODEX_HOME/<profile>.config.toml — and every session card shows the provider and model it was created with. Taking over a session switches the chat to that session's provider and model, and the following messages continue in it.

Use /profile to list the discovered profiles, and /profile <name> to start a new session on one of them (/profile default returns to the base config). While a chat is bound to a profile, /model lists that profile's model catalog. codexProfile on a bot only changes which profile that bot starts from.

To start a fresh session on another profile:

/profile deepseek   switch this chat to the deepseek profile
/new                optional — the next message starts a new session anyway
Reply with exactly: hello

/status then shows Profile deepseek and Model deepseek-flash. The binding is per chat and is persisted, so /new keeps using the same profile until you switch again with /profile default.

Hand sessions back to the Codex app or CLI

Codex allows a single writer per session, and the app server keeps every session it loaded locked until the process exits. So once a bot takes over a session, the Codex app reports it as "open elsewhere" until that bot lets go. Send /release in Telegram to restart the bot's app server and drop every session it holds; the next message reopens this chat's session and locks it again.

/release refuses to run while a turn is active. Sessions held by the Codex app or a CLI are not affected — close them there instead.

4. Install the background service

codex-anywhere install-service

This registers a LaunchAgent (macOS) so the bot starts at login and keeps running when the terminal closes. On Linux, it installs a user-level systemd service.

5. Open Telegram and send /start

Your bot is ready. Try /help to see available commands, or just send a task to begin.

Usage

Send a task to start a new Codex session, or use these commands:

• /new starts fresh
• /resume continues a session from the current workspace
• /continue browses sessions from all workspaces
• /reload refreshes the current session
• /goal shows or changes the current goal
• /account shows, signs in, switches, or signs out of Codex
• /download <path> sends a workspace file back to Telegram
• /upgrade updates Codex Anywhere and relaunches the service
• /upgrade test verifies that the supervised restart helper can run
• /esc stops the active turn

You can also send screenshots, photos, and files. Text files such as .txt, .log, .json, and .crash are sent as readable text so Codex can inspect them directly.

While a turn is running, Telegram keeps progress and run details compact. When Codex finishes, the final answer is sent as a new message that quotes your original request, so it is easy to find and triggers normal Telegram notifications. Queued turns also quote the request they belong to.

Download files from the workspace

Use /download <path> to send files created by Codex back to Telegram. Paths must stay inside the configured workspace or /tmp.

/download <path>          choose the best Telegram format automatically
/download file <path>     send as a file
/download photo <path>    send an image as a Telegram photo
/download zip <path>      send a file or folder as a zip archive
/download list [path]     list files
/download info <path>     show file details

For Oh-My-Codex, send $deep-interview, $autopilot, or other skills directly in chat. Use /omx <args> for OMX commands.

For Computer Use, send /computer <task>. Enable Computer Use in the Codex app first.

Service Management

codex-anywhere restart-service
codex-anywhere service-status
codex-anywhere uninstall-service

Logs are written to logs/ under the Codex Anywhere storage root (CODEX_ANYWHERE_HOME). Upgrade status is recorded there too: upgrade-state.json, upgrade-events.jsonl, and upgrade-restart.log.

Telegram Commands

| Command | Description | |---|---| | /status | Show current thread and model settings | | /version | Show the installed Codex Anywhere version | | /workspace <path> | Show or change the bot workspace | | /addbot | Add another Telegram bot | | /resume | Continue a session in this workspace | | /continue [session-id] | Continue from any workspace | | /reload | Refresh the current session | | /account [status\|login\|switch\|logout] | Manage Codex sign-in | | /goal [status\|set <objective>\|clear] | Manage the current goal | | /download [auto\|file\|photo\|zip\|list\|info] <path> | Send workspace files to Telegram | | /upgrade | Upgrade Codex Anywhere | | /upgrade test | Test the upgrade restart helper without installing | | /omx [args] | Run Oh-My-Codex commands | | /computer <task> | Use Computer Use | | /interrupt, /esc | Interrupt the active turn | | /cancel | Cancel the active prompt or picker |

Many native Codex slash commands also work from Telegram, including /model, /fast, /permissions, /sandbox, /review, /rename, /fork, /compact, /clear, /diff, /mention, /skills, /mcp, /apps, /plugins, /verbose, /logout, and /stop.

Development

Clone and install:

git clone https://github.com/Mempat-AI/codex-anywhere
cd codex-anywhere
pnpm install
pnpm run connect   # runs directly from src/ via tsx
pnpm run add-bot   # appends a new bot definition to config

Run checks:

pnpm run test
pnpm run typecheck
pnpm run build

Tests are local and do not require Telegram, Codex, OMX, or network access.

Contributing

Use pull requests for all changes.

Repository policy:

• PR title gate
• CI gate
• squash merge only

See CONTRIBUTING.md for contribution rules.

Notes

• Single-user (for now), private chats only
• codex must be installed and authenticated before setup
• Config and state live under the user config directory or CODEX_ANYWHERE_HOME
• Background services support macOS LaunchAgent and Linux user-level systemd

Not affiliated with OpenAI.

Built with 💡 in Singapore.