codex-to-im 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 op7418
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# Codex-to-IM
+
+`codex-to-im` is a local bridge app that connects Codex desktop sessions to IM channels such as Feishu/Lark and Weixin.
+
+The product is no longer centered around a Codex skill. The main path is:
+
+1. Install `codex-to-im`
+2. Open the local web workbench
+3. Configure IM channels
+4. Start the bridge in the background
+5. Bind real desktop Codex threads to Feishu or Weixin chats
+
+`SKILL.md` is still kept in the repo, but only as an optional Codex integration entry.
+
+## Project Origin
+
+The current codebase is a consolidated continuation of two earlier repositories:
+
+- `Claude-to-IM`
+- `Claude-to-IM-skill`
+
+`codex-to-im` is based on those two projects and has been reworked toward a single-package local app, shared-thread workflow, and optional Codex integration model.
+
+Windows host installation guide: [docs/install-windows.md](D:/codex/Claude-to-IM-skill/docs/install-windows.md)
+
+## What It Includes
+
+- Local background bridge service
+- Local web workbench for configuration, testing, logs, and bindings
+- Feishu credential setup and connectivity testing
+- Weixin QR login flow
+- Desktop session discovery from `~/.codex/sessions`
+- Web-side binding updates for IM chats
+- Optional Codex integration for opening `codex-to-im` or entering the Feishu handoff flow
+
+## Install
+
+### Prerequisites
+
+- Node.js 20+
+- If you use the `codex` or `auto` runtime, install Codex CLI first
+
+```bash
+npm install -g @openai/codex
+codex auth login
+```
+
+### Global install
+
+```bash
+npm install -g codex-to-im
+```
+
+### Local development
+
+```bash
+npm install
+npm run build
+```
+
+## Run
+
+Start the local app:
+
+```bash
+codex-to-im
+```
+
+This launches the local workbench and opens it in your browser.
+
+By default the workbench runs at:
+
+```text
+http://127.0.0.1:4781
+```
+
+If that port is already occupied, the app automatically finds an available local port and prints the actual address to the terminal when starting.
+
+If you forget the current address, run:
+
+```bash
+codex-to-im url
+```
+
+## Main Workflow
+
+1. Open the workbench
+2. Fill in Feishu credentials or trigger Weixin QR login
+3. Save config and test connectivity
+4. Start the bridge
+5. Open the desktop sessions section
+6. Bind a Feishu or Weixin chat to the target thread
+7. Continue the same Codex thread from IM
+
+Useful command:
+
+- `/history` shows the latest N messages of the current session
+- N is configurable in the web workbench under the basic settings panel
+
+If you enable Feishu streaming response cards, the Feishu app must have the required permissions published first, at minimum:
+
+- `cardkit:card:write`
+- `cardkit:card:read`
+- `im:message:update`
+
+If those permissions are missing, the bridge log will usually show `99991672` with `cardkit:card:write`, and the bridge falls back to a final-result message.
+
+Also note that under the current `codex` runtime, the `Codex CLI / SDK` typically emits the assistant text only when the `agent_message` item is completed, not as token-level deltas. In practice that means Feishu "streaming cards" currently behave more like:
+
+- early `Thinking / Tool Progress` updates
+- final response text written into the card at completion
+
+So character-by-character text streaming is not guaranteed in the current implementation.
+
+If creating a new session fails with `Not inside a trusted directory`, either:
+
+- change the default working directory to a trusted Git repo, or
+- enable `Allow Codex outside trusted Git repos` in the basic settings and restart the bridge
+
+## Optional Codex Integration
+
+The repo still includes a lightweight optional integration under `SKILL.md`.
+
+It is not required for the product to work.
+
+If installed into `~/.codex/skills/codex-to-im`, it should only be used for two actions:
+
+- Open `codex-to-im`
+- Open the Feishu session-sharing entry for the current workflow
+
+You can install that optional integration from the web UI, or with:
+
+```bash
+bash scripts/install-codex.sh --link
+```
+
+## Repo Layout
+
+- `src/ui-server.ts` — local workbench UI and HTTP API
+- `src/service-manager.ts` — bridge and UI lifecycle management
+- `src/desktop-sessions.ts` — desktop thread discovery from Codex session files
+- `src/session-bindings.ts` — binding summaries and web-side binding updates
+- `src/lib/bridge/` — bridge runtime and IM channel routing
+- `SKILL.md` — optional Codex integration only
+- `docs/` — PRD and shared-thread design docs
+
+## Development
+
+```bash
+npm run typecheck
+npm run build
+```
+
+## Status
+
+Current product direction:
+
+- Standalone local app first
+- Web workbench first
+- Shared Codex thread model first
+- Codex integration is optional, not the primary installation path
+
+[中文文档](README_CN.md)

package/README_CN.md

@@ -0,0 +1,161 @@
+# Codex-to-IM
+
+`codex-to-im` 是一个本地桥接应用，用来把 Codex 桌面会话接到飞书、微信等 IM 渠道。
+
+这个项目现在不再以 Skill 为中心。主路径是：
+
+1. 安装 `codex-to-im`
+2. 打开本地 Web 工作台
+3. 配置 IM 渠道
+4. 在后台启动 bridge
+5. 把真实的桌面 Codex thread 绑定到飞书或微信聊天
+
+仓库里仍然保留了 `SKILL.md`，但它只是一个可选的 Codex 集成入口，不再是产品本体。
+
+## 项目来源
+
+当前这套代码是在两个早期仓库的基础上整理和改造出来的：
+
+- `Claude-to-IM`
+- `Claude-to-IM-skill`
+
+现在的 `codex-to-im` 是在这两个工程基础上继续演进的单包版本，重点调整成了本地应用、共享 thread 和可选 Codex 集成的形态。
+
+Windows 主机安装说明见：[docs/install-windows.md](D:/codex/Claude-to-IM-skill/docs/install-windows.md)
+
+## 现在包含什么
+
+- 本地后台 bridge 服务
+- 本地 Web 工作台，用于配置、测试、日志和绑定管理
+- 飞书凭据配置与连通性测试
+- 微信扫码登录
+- 从 `~/.codex/sessions` 发现桌面会话
+- 在网页中查看和切换 IM 绑定
+- 可选的 Codex 集成，仅用于打开 `codex-to-im` 或进入飞书共享入口
+
+## 安装
+
+### 依赖
+
+- Node.js 20+
+- 如果使用 `codex` 或 `auto` 运行时：先安装 Codex CLI
+
+```bash
+npm install -g @openai/codex
+codex auth login
+```
+
+### 全局安装
+
+```bash
+npm install -g codex-to-im
+```
+
+### 本地开发
+
+```bash
+npm install
+npm run build
+```
+
+## 启动
+
+启动本地应用：
+
+```bash
+codex-to-im
+```
+
+它会拉起本地工作台并在浏览器中打开。
+
+默认地址：
+
+```text
+http://127.0.0.1:4781
+```
+
+如果默认端口已被占用，应用会自动选择一个可用端口，并在启动时把实际地址打印到命令行。
+
+如果你忘了当前地址，可以执行：
+
+```bash
+codex-to-im url
+```
+
+## 主流程
+
+1. 打开工作台
+2. 填写飞书配置，或触发微信扫码
+3. 保存配置并测试连通性
+4. 启动 bridge
+5. 打开“最近桌面会话”
+6. 把飞书或微信聊天绑定到目标 thread
+7. 在 IM 中继续同一条 Codex 会话
+
+常用命令补充：
+
+- `/history` 查看当前会话最近 N 条消息
+- N 可在 Web 工作台的“基础配置”里调整
+
+如果你启用了飞书流式响应卡片，需要先在飞书应用侧开通并发布相关权限，至少包括：
+
+- `cardkit:card:write`
+- `cardkit:card:read`
+- `im:message:update`
+
+如果缺少这些权限，Bridge 日志里通常会看到 `99991672` 和 `cardkit:card:write`，系统会自动退回到最终结果消息。
+
+另外要注意：当前 `codex` runtime 下，`Codex CLI / SDK` 实际返回的正文文本事件通常只在 `item.completed` 时出现，不是 token 级逐字输出。所以“飞书流式响应卡片”在当前版本里更准确的含义是：
+
+- 可以先显示 `Thinking / Tool Progress`
+- 正文通常会在回答完成时一次性落到卡片里
+
+也就是说，飞书侧当前不保证像聊天模型网页那样逐字冒字。
+
+如果新建会话时报 `Not inside a trusted directory`，可以：
+
+- 把默认工作目录改成一个你已经信任的 Git 仓库
+- 或在基础配置里打开“允许在未信任 Git 目录运行 Codex”，然后重启 Bridge
+
+## 可选 Codex 集成
+
+仓库里仍然保留了一个很薄的可选集成，定义在 `SKILL.md`。
+
+它不是必需的。
+
+如果你把它装到 `~/.codex/skills/codex-to-im`，它只保留两个动作：
+
+- 打开 `codex-to-im`
+- 打开“共享当前会话到飞书”的入口
+
+你可以在 Web UI 中安装这层可选集成，也可以手动执行：
+
+```bash
+bash scripts/install-codex.sh --link
+```
+
+## 仓库结构
+
+- `src/ui-server.ts` — 本地工作台 UI 和 HTTP API
+- `src/service-manager.ts` — bridge 与 UI 的生命周期管理
+- `src/desktop-sessions.ts` — 从 Codex 会话文件发现桌面 thread
+- `src/session-bindings.ts` — 绑定摘要与网页侧切换
+- `src/lib/bridge/` — bridge 运行时与 IM 路由
+- `SKILL.md` — 可选 Codex 集成，不是主产品
+- `docs/` — PRD 与共享 thread 技术设计
+
+## 开发
+
+```bash
+npm run typecheck
+npm run build
+```
+
+## 当前方向
+
+- 先做独立本地应用
+- 先做 Web 工作台
+- 先做共享 Codex thread
+- Codex 集成是可选增强，不是主安装路径
+
+[English](README.md)

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security
+
+## Credential Storage
+
+Credentials are stored in `~/.codex-to-im/config.env` and the local runtime data under `~/.codex-to-im/`.
+
+The app still falls back to `~/.claude-to-im/` on machines that already have legacy data, but new installs should treat `~/.codex-to-im/` as the primary home.
+
+This repository never stores secrets in source control.
+
+## Log Redaction
+
+Tokens and secrets should be masked in logs and workbench output. Only short tail fragments of secrets should ever be shown for confirmation or diagnosis.
+
+## Operational Model
+
+`codex-to-im` is a local single-user bridge:
+
+- The bridge runs on the user's machine
+- The web workbench is local-only
+- IM authentication is delegated to each IM platform
+- Access control is enforced through configured allowlists and channel bindings
+
+## Rotation Guidance
+
+If a token is rotated or suspected to be exposed:
+
+1. Revoke the old credential on the IM platform
+2. Update the value in the local `codex-to-im` workbench
+3. Restart the bridge from the workbench
+4. Review recent logs under `~/.codex-to-im/logs/`
+
+## Legacy Data
+
+If you upgraded from an older `claude-to-im` install, check both of these locations during diagnosis:
+
+- `~/.codex-to-im/`
+- `~/.claude-to-im/`

package/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: codex-to-im
+description: |
+  Optional Codex integration for the codex-to-im local app. Use only when the
+  user wants to open codex-to-im from Codex or enter the Feishu session-sharing
+  flow. Do not use this skill as the main setup, config, logs, or daemon
+  management path.
+argument-hint: "open | share-feishu"
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Codex-to-IM Optional Integration
+
+`codex-to-im` is a standalone local app with a background bridge and web workbench.
+
+This optional integration is intentionally thin. It exists only for two actions:
+
+- `open`
+- `share-feishu`
+
+If the user asks to configure channels, start or stop the bridge, inspect logs, or diagnose issues, do not treat this integration as the main workflow. Open the local app instead.
+
+## Resolve the repo / install root
+
+Prefer these locations:
+
+- `~/.codex/skills/codex-to-im`
+- `~/.claude/skills/codex-to-im`
+
+If neither exists, fall back to globbing `**/skills/**/codex-to-im/SKILL.md` and derive the root from that match.
+
+## Command mapping
+
+Map user intent to one of these two actions:
+
+| User says | Action |
+|---|---|
+| `open codex-to-im`, `打开 codex-to-im`, `open bridge workbench`, `打开工作台` | `open` |
+| `share current session to feishu`, `共享当前会话到飞书`, `把当前会话发到飞书`, `open feishu handoff` | `share-feishu` |
+
+## Execution
+
+### `open`
+
+Prefer:
+
+```bash
+codex-to-im open
+```
+
+If the `codex-to-im` command is unavailable, fall back to:
+
+```bash
+node dist/cli.mjs open
+```
+
+Run from the repo / install root.
+
+### `share-feishu`
+
+Prefer:
+
+```bash
+codex-to-im share-feishu
+```
+
+If the `codex-to-im` command is unavailable, fall back to:
+
+```bash
+node dist/cli.mjs share-feishu
+```
+
+Run from the repo / install root.
+
+After opening the workbench, tell the user to use the desktop sessions panel or the IM binding panel to finish binding the target thread to Feishu.

package/config.env.example

@@ -0,0 +1,106 @@
+# Codex-to-IM Configuration
+# Copy to ~/.codex-to-im/config.env and edit
+
+# Runtime backend: claude | codex | auto
+#   claude (default) — uses Claude Code CLI + @anthropic-ai/claude-agent-sdk
+#   codex  — uses @openai/codex-sdk (auth: codex auth login, or OPENAI_API_KEY)
+#   auto   — tries Claude first, falls back to Codex if CLI not found
+# If you plan to use the codex runtime, install Codex CLI first:
+#   npm install -g @openai/codex
+#   codex auth login
+CTI_RUNTIME=claude
+
+# Enabled channels (comma-separated: telegram,discord,feishu,qq,weixin)
+CTI_ENABLED_CHANNELS=telegram
+
+# Default working directory for Codex / bridge sessions
+CTI_DEFAULT_WORKDIR=/path/to/your/project
+
+# Default model (optional — inherits from runtime's own default if not set)
+# CTI_DEFAULT_MODEL=
+
+# Default mode (code, plan, ask)
+CTI_DEFAULT_MODE=code
+
+# Number of recent messages returned by /history
+# CTI_HISTORY_MESSAGE_LIMIT=8
+
+# ── Claude CLI path (optional) ──
+# Override if you have multiple `claude` versions in PATH, or the daemon
+# picks the wrong one (e.g. an npm-installed 1.x instead of the native 2.x).
+# CTI_CLAUDE_CODE_EXECUTABLE=/path/to/claude
+
+# ── Third-party API provider (optional) ──
+# If you use Claude through a third-party API provider (not the default
+# Anthropic API), set these so the daemon forwards them to the CLI subprocess.
+# They are automatically passed through in both inherit and strict env modes.
+# All ANTHROPIC_* vars in this file are forwarded to the launchd/setsid daemon.
+# ANTHROPIC_API_KEY=your-third-party-api-key
+# ANTHROPIC_BASE_URL=https://your-api-provider.com/v1
+# ANTHROPIC_AUTH_TOKEN=your-auth-token
+
+# ── Codex auth (optional — only if not using `codex auth login`) ──
+# Priority: CTI_CODEX_API_KEY > CODEX_API_KEY > OPENAI_API_KEY
+# CTI_CODEX_API_KEY=
+# CTI_CODEX_BASE_URL=
+# Allow Codex to run when CTI_DEFAULT_WORKDIR is not inside a trusted Git repo.
+# Keep this off unless you intentionally want Codex to work in arbitrary folders.
+# CTI_CODEX_SKIP_GIT_REPO_CHECK=true
+
+# ── Telegram ──
+CTI_TG_BOT_TOKEN=your-telegram-bot-token
+# Chat ID for authorization (at least one of CHAT_ID or ALLOWED_USERS is required)
+# Get it: send a message to the bot, then visit https://api.telegram.org/botYOUR_TOKEN/getUpdates
+CTI_TG_CHAT_ID=your-chat-id
+# CTI_TG_ALLOWED_USERS=user_id_1,user_id_2
+
+# ── Discord ──
+# CTI_DISCORD_BOT_TOKEN=your-discord-bot-token
+# CTI_DISCORD_ALLOWED_USERS=user_id_1,user_id_2
+# CTI_DISCORD_ALLOWED_CHANNELS=channel_id_1
+# CTI_DISCORD_ALLOWED_GUILDS=guild_id_1
+
+# ── Feishu / Lark ──
+# CTI_FEISHU_APP_ID=your-app-id
+# CTI_FEISHU_APP_SECRET=your-app-secret
+# CTI_FEISHU_DOMAIN=https://open.feishu.cn
+# CTI_FEISHU_ALLOWED_USERS=user_id_1,user_id_2
+# Enable streaming response cards in Feishu (default true).
+# Requires published Feishu permissions such as:
+#   - cardkit:card:write
+#   - cardkit:card:read
+#   - im:message:update
+# Current Codex runtime note: thinking/progress can update live, but
+# assistant body text may still arrive only at completion.
+# CTI_FEISHU_STREAMING_ENABLED=true
+
+# ── QQ ──
+# Required: obtain from https://q.qq.com/qqbot/openclaw
+# CTI_QQ_APP_ID=your-qq-app-id
+# CTI_QQ_APP_SECRET=your-qq-app-secret
+# Allowed users — comma-separated user_openid values (NOT QQ numbers)
+# CTI_QQ_ALLOWED_USERS=openid_1,openid_2
+# Image input — set to false if the underlying provider doesn't support image input
+# CTI_QQ_IMAGE_ENABLED=true
+# Max image size in MB (default 20)
+# CTI_QQ_MAX_IMAGE_SIZE=20
+
+# ── WeChat / 微信 ──
+# No static token is required here. Use the QR login helper to add accounts:
+#   npm run weixin:login
+# Optional protocol overrides (normally leave unset)
+# CTI_WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
+# CTI_WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c
+# Enable inbound media download/processing for image/file/video messages.
+# Voice messages do not use raw audio download/transcription here: the bridge
+# only accepts WeChat-provided speech-to-text text and otherwise returns an error.
+# (default false for safety in CLI setups)
+# CTI_WEIXIN_MEDIA_ENABLED=false
+
+# ── Permission ──
+# Auto-approve all tool permission requests without user confirmation.
+# Useful for channels that lack interactive permission UI (e.g. Feishu
+# WebSocket long-connection mode, where there is no HTTP webhook to
+# render clickable approve/deny buttons).
+# ⚠️  Only enable this in trusted, access-controlled environments.
+# CTI_AUTO_APPROVE=true