CodexClaw

A Telegram bot that gives you remote access to @openai/codex through a Node.js runtime with two Codex backends: the Codex SDK and the legacy CLI/PTy path.
It is strictly inspired by RichardAtCT/claude-code-telegram, but this project is implemented for CodeX SDK/CLI + MCP + Subagent routing.

What Is This?

This bot connects Telegram to Codex and routes tasks to the right execution surface:

• Coding tasks -> Codex SDK threads or Codex CLI/PTy sessions
• Explicit tool tasks -> Subagents (/mcp, GitHub Skill)
• Proactive automation -> Cron scheduler for daily summaries and push notifications

Key design goals:

• Keep Codex interactive sessions smooth and stream-safe on Telegram
• Enforce zero-trust access with whitelist-only users
• Avoid duplicate MCP calls by separating Codex MCP vs Bot MCP responsibilities
• Prefer the SDK backend for new installs, while keeping the CLI backend as a fallback

Use This Like A Skill

What It Does

• installs a Telegram-facing Codex runtime
• keeps Codex live sessions scoped to chat + repo
• manages bot-side MCP and GitHub subagents
• exposes repo switching, status, and minimal frontend dev-server control from Telegram

Install

git clone https://github.com/MackDing/CodexClaw.git
cd CodexClaw
npm install
cp .env.example .env

Configure The Minimum

BOT_TOKEN=123456789:telegram-token
ALLOWED_USER_IDS=123456789
STATE_FILE=.codex-telegram-claws-state.json
WORKSPACE_ROOT=.
CODEX_WORKDIR=.
CODEX_BACKEND=sdk

Start The Skill

npm run start

Telegram Quick Use

/status
/repo
/skill
/dev status
/gh create repo my-new-app

For agent-oriented setup, see SKILL.md.

Quick Start

Prerequisites

• Node.js 20+ -- https://nodejs.org/en/download/current
• Codex CLI -- https://github.com/openai/codex
• Telegram Bot Token -- from @BotFather

Development Commands

• npm run start - start the bot
• npm run dev - watch mode for local development
• npm run check - TypeScript type and syntax validation for the repository
• npm run typecheck - run the TypeScript compiler in --noEmit mode
• npm run lint - ESLint for source, tests, scripts, and local JS/CJS config files
• npm run lint:fix - apply safe lint fixes
• npm run format - format repository files with Prettier
• npm run format:check - verify formatting
• npm test - run the full test suite
• npm run healthcheck - static runtime readiness check
• npm run healthcheck:strict - stricter production-oriented health check
• npm run healthcheck:live - live Codex + Telegram probe against the configured backend and bot token
• npm run telegram:smoke - live Telegram API smoke test when a real bot token is available

Architecture

Telegram Message
  -> src/bot/handlers.ts
  -> src/orchestrator/router.ts
     -> src/runner/ptyManager.ts        (coding tasks -> Codex SDK or Codex CLI)
     -> src/orchestrator/skills/*.ts    (general tasks -> MCP/GitHub subagents)
  -> src/bot/formatter.ts
  -> Telegram sendMessage/editMessageText

Core modules:

• src/index.ts: bootstrap and lifecycle
• src/config.ts: env parsing and validation
• src/bot/: auth middleware, formatting, command handlers
• src/orchestrator/: routing + MCP client + skills
• src/runner/ptyManager.ts: Codex runner abstraction for SDK threads, CLI/PTy sessions, and CLI exec fallback
• src/cron/scheduler.ts: proactive scheduled push