CodexClaw

# CodexClaw

> A Telegram bot for remote access to OpenAI Codex with full AI assistance, MCP integration, and session persistence.

## What is CodexClaw?

CodexClaw 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

## Key Features

- Two Codex backends: SDK (preferred) and CLI/PTy (legacy fallback)
- Project-scoped conversation state per chat + repo
- Workspace contention guard — prevents concurrent writes
- MCP and GitHub subagent routing
- Streaming output with reasoning visualization
- Zero-trust access with whitelist-only users
- Frontend debugging layer (start/stop/logs dev servers)
- Safe shell access (optional, read-only by default)

## Architecture

Telegram Message → handlers.ts → router.ts → (Codex SDK | Codex CLI | Subagents) → formatter.ts → Telegram

## Tech Stack

TypeScript, Node.js 20+, @openai/codex-sdk, telegraf, node-pty, node-cron, MCP SDK

## Links

- Repository: https://github.com/MackDing/CodexClaw
- Author: https://github.com/MackDing
- OPC Hub: https://opc.ren