DeskWeave

简体中文

Documentation: Architecture · Remote protocol · Research · Roadmap

DeskWeave bridges mobile chat channels to the same task open in a desktop AI client. The current MVP lets a Feishu bot control the official Codex Windows app through its Remote Control protocol; it does not spawn a separate Codex CLI process or automate pixels and keyboard input.

flowchart LR
  F[Feishu phone] <--> B[Local bridge on 127.0.0.1]
  B <--> A[Official Codex App Server]
  A <--> T[One shared Codex task]
  T --> W[Windows Codex GUI]
  T --> F

Loading

Implemented

• List and select existing Codex tasks with /tasks and /use.
• Send text or Feishu voice into the selected desktop task.
• Stream agent output back to one editable Feishu message.
• Approve or deny command, file, permission, and MCP requests.
• Stop the active turn with /stop.
• Loopback-only Remote backend with protocol v3 and bearer-token validation.
• Reversible Codex enrollment installer that does not replace the model provider or proxy model traffic.
• Windows Task Scheduler helper.
• In-memory Feishu and Codex mocks for credential-free end-to-end tests.

This first MVP targets Codex + Feishu. WeChat and Claude Desktop adapters are not included yet.

Project status

DeskWeave is pre-alpha software. The protocol core and reversible installer are covered by local end-to-end mocks, but a real Codex App + Feishu account test still requires user-owned credentials and an explicit Codex restart.

Verify locally

npm install
npm run check
npm run test:mock

The mock run should report codexConnected: true, codexInitialized: true, and a final mobile event containing Mock Codex is working in the same desktop task.

Feishu setup

Create a custom Feishu app and enable its bot capability. Add the im.message.receive_v1 event and use long connection mode. Grant at least these tenant permissions:

• Read bot messages and message resources.
• Send messages as the bot.
• speech_to_text:speech if voice control is needed.

Copy config.example.json to config.local.json, enable Feishu, and fill the allowlists. Keep the secret outside source control; production should provide it through FEISHU_APP_SECRET.

$env:FEISHU_APP_SECRET = '<secret>'
$env:DESKWEAVE_SECRET = '<at-least-32-random-characters>'
npm run build
npm start

The bridge binds only to 127.0.0.1. Do not expose port 3847 to the LAN or internet.

Attach the official Codex app

The installer writes only these Codex local state entries:

• remote_control feature enablement.
• A Remote enrollment pointing to ws://127.0.0.1:3847/backend-api/wham/remote/control/server.
• app-server-daemon/settings.json remote-control switch.

It records previous values in ~/.codex/.deskweave/install-manifest.json so uninstall can restore them exactly. It does not edit config.toml, replace the current model provider, or copy authentication tokens.

Close Codex Windows before install or uninstall so its SQLite databases are not busy:

npm run codex:config -- status
npm run codex:config -- install

Start the bridge, then restart Codex Windows. Check bridge health at http://127.0.0.1:3847/api/status.

Rollback:

npm run codex:config -- uninstall

The installer has been tested against isolated mock Codex state databases. It has deliberately not been run against the active Codex app in this workspace.

Phone commands

Command	Action
/tasks	List recent desktop tasks
/use 2	Select task 2
/use <thread-id>	Select by exact task ID
Any other text	Start a turn in the selected task
Voice message	Transcribe with Feishu ASR, then start a turn
/stop	Interrupt the active turn
/approve [id]	Approve the pending request
/deny [id]	Deny the pending request
/status	Show Remote connection state

Windows startup

After a real Feishu test succeeds:

powershell -ExecutionPolicy Bypass -File .\scripts\install-startup.ps1

Remove it with:

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-startup.ps1

Security notes

• Both the Feishu user and chat must be allowlisted.
• A phone approval has the same authority as a local Codex approval.
• Remote protocol messages are acknowledged before Feishu rendering to avoid App Server backpressure disconnects.
• Non-interactive or unknown Codex approval methods fail closed.
• The release should be packaged and signed before unattended deployment.

Acknowledgements

Remote compatibility research was informed by OpenAI's public Codex App Server documentation and the Apache-2.0 CodexHub implementation. See THIRD_PARTY_NOTICES.md.