Codex CC Web Terminal

A local-first web console for controlling desktop Codex sessions from a browser, phone, or Feishu bot.

The project is designed for long-running development tasks where the actual work happens on your desktop, while your phone acts as a lightweight control surface for status checks, approvals, follow-up instructions, and interrupts.

简体中文

What It Does

• Runs a local web terminal for Codex sessions.
• Provides a mobile console with realtime WebSocket updates.
• Supports Feishu private-chat commands as a mobile entry point.
• Sends short-lived mobile console links instead of exposing the main access token.
• Supports task continuation, interrupt, approvals, and supplemental input.
• Uses PM2 helpers for desktop background services.
• Includes a PowerShell command watchdog for commands that may run too long.

Architecture

Phone Feishu chat
  -> Feishu bot bridge
  -> local web service on desktop
  -> Codex app-server / Codex CLI
  -> realtime WebSocket mobile console
  -> status, approval, interrupt, and final result back to phone

Feishu is used as the notification and command entry channel. The mobile web console is used for realtime output, continuing input, interrupting tasks, and handling blocking interactions.

Requirements

• Node.js 22+
• npm
• Codex CLI installed and available in PATH
• A Feishu/Lark app if you want Feishu integration
• Tailscale, LAN, or another private network path if your phone is not on the same machine/network

Quick Start

git clone https://github.com/Robin-fang611/codex-feishu-mobile-control.git
cd codex-feishu-mobile-control
npm install
cp .env.example .env
npm run check
npm run start

Open:

http://127.0.0.1:3210

Set ACCESS_TOKEN in .env before exposing the service beyond localhost.

Recommended Mobile Setup

1. Install Tailscale on the desktop and phone.
2. Log in to the same Tailnet.
3. Set .env:

HOST=0.0.0.0
TAILSCALE_ONLY=true
MOBILE_PUBLIC_BASE_URL=http://<desktop-tailscale-ip>:3210

4. Start services:

npm run remote:start
npm run remote:status

5. On the phone, open the mobile console link returned by Feishu or visit:

http://<desktop-tailscale-ip>:3210

Feishu Bot Setup

Create a Feishu app, enable bot capability and event subscription, then configure .env:

FEISHU_APP_ID=
FEISHU_APP_SECRET=
FEISHU_SESSION_RUNNER_MODE=app_server
FEISHU_DEFAULT_CWD=/path/to/your/workspace
FEISHU_REQUIRE_BIND=true

You can also write credentials with:

npm run feishu:config -- -AppId <your_app_id> -AppSecret <your_app_secret>

Start the full remote stack:

npm run remote:start
npm run remote:status

Useful commands in Feishu private chat:

新会话
状态
控制台
中断
继续 <your instruction>
待处理
/approve <ID>
/reject <ID>
/reply <ID> <text>

Any other text is treated as a Codex task prompt.

Important Scripts

npm run check                         # Syntax checks + web build
npm run test:app-server-interactions  # app-server interaction smoke
npm run test:feishu-interactions      # Feishu command smoke
npm run remote:start                  # web service + Feishu bridge + watchdog
npm run remote:restart                # restart all remote services
npm run remote:status                 # inspect all services
npm run remote:stop                   # stop all remote services
npm run command:watchdog -- -CheckAfterMinutes 1 -KillAfterMinutes 3 -CommandText "npm run check"

Use command:watchdog for commands that may run longer than one minute.

Security Notes

• Do not commit .env, data/, logs/, .pm2/, or temp/.
• Keep ACCESS_TOKEN strong and private.
• Prefer TAILSCALE_ONLY=true or strict TRUSTED_CIDRS for phone access.
• Do not expose this service directly to the public internet without additional authentication and network controls.
• Feishu mobile links are short-lived and should be treated as bearer tokens until they expire.

Development

npm install
npm run dev

For production-like local service management:

npm run service:start
npm run service:status
npm run service:logs

Validation Before Publishing

npm run check
npm run test:app-server-interactions
npm run test:feishu-interactions

License

MIT. See LICENSE.