CodeX-to-IM Skill

Bridge Codex-first coding sessions to IM platforms so you can drive coding work from Telegram, Discord, Feishu/Lark, or QQ.

中文文档

Want a desktop GUI instead? Check out CodePilot — a full-featured desktop app with visual chat interface, session management, file tree preview, permission controls, and more. This skill was extracted from CodePilot's IM bridge module for users who prefer a lightweight, CLI-only setup.

---

Why

• Chat with Codex or Claude Code from Telegram, Discord, Feishu/Lark, or QQ
• Approve tool calls from chat instead of sitting in front of the terminal
• Keep a local daemon and local filesystem control instead of building a hosted bot stack

Quick Start

git clone https://github.com/xiaolin26/Codex-to-im-skill.git ~/.codex/skills/codex-to-im
bash ~/.codex/skills/codex-to-im/scripts/install-codex.sh --link
codex login

Then in Codex or Claude Code:

codex-to-im setup
codex-to-im start

First-Time Onboarding

There is onboarding for both environments:

• Claude Code: step-by-step setup wizard using interactive questions
• Codex: chat-based guided setup that asks for values one by one, writes ~/.codex-to-im/config.env, and can start the bridge for you

For the smoothest first run:

1. Install the skill into ~/.codex/skills/codex-to-im
2. Run codex login
3. Start the setup flow with codex-to-im setup
4. Run bash scripts/doctor.sh
5. Run bash scripts/daemon.sh start

Use a real project directory as CTI_DEFAULT_WORKDIR when possible. If you intentionally use a non-repo directory, set CTI_CODEX_SKIP_GIT_REPO_CHECK=true.

How It Works

This project runs a background daemon that connects your IM bots to Codex or Claude Code sessions. Messages from IM are forwarded to the coding agent, and responses (including tool use, permission requests, and streaming previews) are sent back to your chat.

You (Telegram/Discord/Feishu/QQ)
  ↕ Bot API
Background Daemon (Node.js)
  ↕ Codex SDK or Claude Agent SDK (configurable via CTI_RUNTIME)
Codex / Claude Code → reads/writes your codebase

Features

• Four IM platforms — Telegram, Discord, Feishu/Lark, QQ — enable any combination
• First-run guidance — interactive setup in Claude Code, guided chat-based setup in Codex
• Permission control — tool calls require explicit approval via inline buttons (Telegram/Discord) or text /perm commands (Feishu/QQ)
• Streaming preview — see Claude's response as it types (Telegram & Discord)
• Session persistence — conversations survive daemon restarts
• Secret protection — tokens stored with chmod 600, auto-redacted in all logs
• Codex-first defaults — new installs default to CTI_RUNTIME=codex and store state in ~/.codex-to-im
• Legacy migration — automatically reuses ~/.claude-to-im if that older directory already exists

Prerequisites

• Node.js >= 20
• Claude Code CLI (for CTI_RUNTIME=claude or auto) — installed and authenticated (claude command available)
• Codex CLI (for CTI_RUNTIME=codex or auto) — npm install -g @openai/codex. Auth: run codex login, or set OPENAI_API_KEY (optional, for API mode)

Installation

Local development

cp -R /path/to/CodeX-to-IM-skill ~/.codex/skills/codex-to-im

Git clone

git clone <your-repo-url> ~/.codex/skills/codex-to-im

Or use the provided install script for automatic dependency installation and build:

# Clone and install (copy mode)
git clone <your-repo-url> ~/code/CodeX-to-IM-skill
bash ~/code/CodeX-to-IM-skill/scripts/install-codex.sh

# Or use symlink mode for development
bash ~/code/CodeX-to-IM-skill/scripts/install-codex.sh --link

Verify installation

Codex: Start a new session and say codex-to-im setup or start bridge.

Claude Code: Install the same repo under ~/.claude/skills/codex-to-im if you also want Claude-side invocation.

1. Setup

/codex-to-im setup

The setup flow covers:

1. Choose channels — pick Telegram, Discord, Feishu, QQ, or any combination
2. Enter credentials — the wizard explains exactly where to get each token, which settings to enable, and what permissions to grant
3. Set defaults — working directory, model, and mode
4. Validate — tokens are verified against platform APIs immediately

2. Start

/codex-to-im start

The daemon starts in the background. You can close the terminal — it keeps running.

3. Chat

Open your IM app and send a message to your bot. Codex will respond.

When the agent needs to use a tool (edit a file, run a command), you'll see a permission prompt with Allow / Deny buttons right in the chat (Telegram/Discord), or a text /perm command prompt (Feishu/QQ).

Recommended First Run

If you want the least-friction first run on Codex, use a real project directory as CTI_DEFAULT_WORKDIR instead of ~/Downloads. If you really want a non-repo directory, set CTI_CODEX_SKIP_GIT_REPO_CHECK=true.

Commands

All commands are run inside Codex or Claude Code:

Slash / alias	Codex (natural language)	Description
/codex-to-im setup	"codex-to-im setup" / "配置"	Interactive setup wizard
/codex-to-im start	"start bridge" / "启动桥接"	Start the bridge daemon
/codex-to-im stop	"stop bridge" / "停止桥接"	Stop the bridge daemon
/codex-to-im status	"bridge status" / "状态"	Show daemon status
/codex-to-im logs	"查看日志"	Show last 50 log lines
/codex-to-im logs 200	"logs 200"	Show last 200 log lines
/codex-to-im reconfigure	"reconfigure" / "修改配置"	Update config interactively
/codex-to-im doctor	"doctor" / "诊断"	Diagnose issues

Platform Setup Guides

The setup wizard provides inline guidance for every step. Here's a summary:

Telegram

1. Message @BotFather on Telegram → /newbot → follow prompts
2. Copy the bot token (format: 123456789:AABbCc...)
3. Recommended: /setprivacy → Disable (for group use)
4. Find your User ID: message @userinfobot

Discord

1. Go to Discord Developer Portal → New Application
2. Bot tab → Reset Token → copy it
3. Enable Message Content Intent under Privileged Gateway Intents
4. OAuth2 → URL Generator → scope bot → permissions: Send Messages, Read Message History, View Channels → copy invite URL

Feishu / Lark

1. Go to Feishu Open Platform (or Lark)
2. Create Custom App → get App ID and App Secret
3. Batch-add permissions: go to "Permissions & Scopes" → use batch configuration to add all required scopes (the setup wizard provides the exact JSON)
4. Enable Bot feature under "Add Features"
5. Events & Callbacks: select "Long Connection" as event dispatch method → add im.message.receive_v1 event
6. Publish: go to "Version Management & Release" → create version → submit for review → approve in Admin Console
7. Important: The bot will NOT work until the version is approved and published

QQ

QQ currently supports C2C private chat only. No group/channel support, no inline permission buttons, no streaming preview. Permissions use text /perm ... commands. Image inbound only (no image replies).

1. Go to QQ Bot OpenClaw
2. Create a QQ Bot or select an existing one → get App ID and App Secret (only two required fields)
3. Configure sandbox access and scan QR code with QQ to add the bot
4. CTI_QQ_ALLOWED_USERS takes user_openid values (not QQ numbers) — can be left empty initially
5. Set CTI_QQ_IMAGE_ENABLED=false if the underlying provider doesn't support image input

Architecture

~/.codex-to-im/
├── config.env             ← Credentials & settings (chmod 600)
├── data/                  ← Persistent JSON storage
│   ├── sessions.json
│   ├── bindings.json
│   ├── permissions.json
│   └── messages/          ← Per-session message history
├── logs/
│   └── bridge.log         ← Auto-rotated, secrets redacted
└── runtime/
    ├── bridge.pid          ← Daemon PID file
    └── status.json         ← Current status

Key components

Component	Role
src/main.ts	Daemon entry — assembles DI, starts bridge
src/config.ts	Load/save config.env, map to bridge settings
src/store.ts	JSON file BridgeStore (30 methods, write-through cache)
src/llm-provider.ts	Claude Agent SDK query() → SSE stream
src/codex-provider.ts	Codex SDK runStreamed() → SSE stream
src/sse-utils.ts	Shared SSE formatting helper
src/permission-gateway.ts	Async bridge: SDK canUseTool ↔ IM buttons
src/logger.ts	Secret-redacted file logging with rotation
scripts/daemon.sh	Process management (start/stop/status/logs)
scripts/doctor.sh	Health checks
SKILL.md	Skill definition for Codex / Claude Code

Permission flow

1. Codex wants to use a tool (e.g., Edit file)
2. SDK calls canUseTool() → LLMProvider emits permission_request SSE
3. Bridge sends inline buttons to IM chat: [Allow] [Deny]
4. canUseTool() blocks, waiting for user response (5 min timeout)
5. User taps Allow → bridge resolves the pending permission
6. SDK continues tool execution → result streamed back to IM

Troubleshooting

Run diagnostics:

/codex-to-im doctor

This checks: Node.js version, config file existence and permissions, token validity (live API calls), log directory, PID file consistency, and recent errors.

Issue	Solution
Bridge won't start	Run doctor. Check if Node >= 20. Check logs.
Messages not received	Verify token with doctor. Check allowed users config.
Permission timeout	User didn't respond within 5 min. Tool call auto-denied.
Stale PID file	Run stop then start. daemon.sh auto-cleans stale PIDs.

See references/troubleshooting.md for more details.

Security

• All credentials stored in ~/.codex-to-im/config.env with chmod 600
• Tokens are automatically redacted in all log output (pattern-based masking)
• Allowed user/channel/guild lists restrict who can interact with the bot
• The daemon is a local process with no inbound network listeners
• See SECURITY.md for threat model and incident response

Development

npm install        # Install dependencies
npm run dev        # Run in dev mode
npm run typecheck  # Type check
npm test           # Run tests
npm run build      # Build bundle

License

MIT