wechat-codex

Turn WeChat into a mobile front-end for your local Codex CLI.

wechat-codex is a local bridge that lets you talk to your own Codex-powered coding environment from your phone.
The long-term goal is simple: text your machine on WeChat, let it run Codex locally, and get useful answers back with strong local-state, queueing, and safety guarantees.

中文说明

Why This Exists

Most AI coding tools assume you are sitting in front of a laptop.

That breaks in real life:

• you want to inspect a repo while commuting
• you want to kick off a task from your phone
• you want your AI agent to run on your machine, with your files, not inside a hosted black box
• you want a local, inspectable bridge instead of a SaaS wrapper around Codex

wechat-codex is building that missing layer.

What Makes It Interesting

• WeChat as the UI: no extra mobile app, no browser tab maze
• Codex runs locally: your repos, your credentials, your machine
• Queue-first architecture: designed for long-running background use, not one-off toy demos
• SQLite as the source of truth: persistent jobs, runtime summary, confirmations, audit trail
• Safety-by-default: explicit sandbox modes, durable confirmations, local control
• Built for boring reliability: single binary, explicit state machine, recoverable runtime model

Project Status

This repo is in an active Rust rewrite.

What is true today

• the old Node/TypeScript implementation has been removed from the repo
• the new Rust codebase and architecture are now the source of truth
• core pieces already exist:
  • CLI skeleton
  • SQLite schema and repository thread
  • durable job queue model
  • runtime state summary for /status
  • queue drain path
  • Codex runner boundary
  • launchctl/systemd service management code
  • ilink QR login and text-message polling/reply path
  • ilink attachment download/decrypt/store path for image/voice/file/video
  • /help /status /model /cwd /sandbox /confirm command flow
  • durable confirmation flow, allowlist checks, and PartialSent
  • maintenance / retention cleanup logic

What is not true yet

• this is not production-ready today
• non-text attachment understanding still needs real-machine validation
• service install, long-running behavior, and real reply delivery still need machine-level validation
• the npm wrapper exists in-repo, but no public package has been published yet
• the repo currently reflects a serious in-progress build, not a finished release

If you star the project now, you are effectively following the build-out of a local-first WeChat × Codex runtime.

Product Direction

The Rust version is intentionally a new product, not a compatibility patch over the old daemon.

Key decisions already locked:

• new service identity
• new default data directory
• no automatic legacy data import
• single-account, single-machine, FIFO execution model
• durable state in SQLite
• explicit confirmation flow for risky actions
• launchd + systemd as the target service story

Architecture

WeChat API
   |
   v
wechat_io -----> queue -----> codex_runner
   |               |              |
   |               v              v
   |----------> state_repo <------|
                   |
                   v
                SQLite

security_audit <--- wechat_io / queue / codex_runner / state_repo

Core Design Principles

• Local-first: the useful work should happen on your machine
• Explicit state over magic: if the daemon crashes, state should still be explainable
• Single-user focus: avoid fake platform complexity
• Queue semantics matter: incoming jobs freeze their execution context at enqueue time
• Boring tools win: Rust + SQLite + subprocesses beats unnecessary orchestration

Current CLI Shape

The Rust binary is evolving toward this command model:

wechat-codex setup
wechat-codex daemon-run
wechat-codex service install
wechat-codex service start
wechat-codex service stop
wechat-codex service restart
wechat-codex service status
wechat-codex logs
wechat-codex status
wechat-codex maintenance

There is also a temporary debug-only enqueue command in the current codebase to help verify the queue path during development.

Quick Look At The Data Model

The Rust rewrite already centers on these durable tables:

• jobs
• runtime_state
• settings
• confirmations
• audit_events
• actors

The important idea is that jobs are immutable execution snapshots and runtime_state is a live summary, not a dumping ground for everything.

Development

Requirements

• Rust stable
• Codex CLI installed locally
• a machine where WeChat bridge development is feasible

Build

cd rust
cargo build

Format

cd rust
cargo fmt --check

Test

cd rust
env GIT_CONFIG_GLOBAL=/dev/null HTTP_PROXY= HTTPS_PROXY= ALL_PROXY= cargo test

Local Dogfooding

1. Run setup once

cd /Users/monkeyin/projects/wechat-codex/rust
cargo run -- --data-dir /tmp/wechat-codex-rs-dev setup

setup now writes a persistent config.json and, by default, performs an ilink QR bind flow directly in the terminal. After that, daemon-run / service start read the saved bot token and sync cursor automatically.

2. Start the daemon

cd /Users/monkeyin/projects/wechat-codex/rust
cargo run -- --data-dir /tmp/wechat-codex-rs-dev daemon-run

3. Install it as a service

cd /Users/monkeyin/projects/wechat-codex/rust
cargo run -- --data-dir /tmp/wechat-codex-rs-dev service install
cargo run -- --data-dir /tmp/wechat-codex-rs-dev service start

4. npm install

npm install -g wechat-codex
wechat-codex doctor
wechat-codex setup

This uses a thin Node wrapper plus the Rust binary. Published installs download the matching prebuilt binary from GitHub Releases during postinstall.

For an unpublished source checkout, keep using cargo run or build rust/Cargo.toml manually first.

5. Optional environment overrides

Most config now lives in config.json; environment variables are mainly overrides or advanced switches:

export WECHAT_CODEX_ENABLE_DANGER=1
export WECHAT_CODEX_DAEMON_POLL_INTERVAL_SECS=2

6. Current important environment variables

• WECHAT_CODEX_ALLOWLIST
• WECHAT_CODEX_ILINK_BASE_URL
• WECHAT_CODEX_ILINK_BOT_TOKEN
• WECHAT_CODEX_ILINK_BOT_ID
• WECHAT_CODEX_DAEMON_POLL_INTERVAL_SECS
• WECHAT_CODEX_REPLY_CHUNK_CHARS
• WECHAT_CODEX_ENABLE_DANGER
• WECHAT_CODEX_CONFIRMATION_RETENTION_DAYS
• WECHAT_CODEX_JOB_RETENTION_DAYS
• WECHAT_CODEX_AUDIT_RETENTION_DAYS
• WECHAT_CODEX_INBOUND_RETENTION_DAYS

7. Debug-only local mock bridge

The repo still keeps a local http:// mock server for development fallback:

cd /Users/monkeyin/projects/wechat-codex
python3 scripts/mock_wechat_server.py

If you use this path, the old override variables still work:

• WECHAT_CODEX_WECHAT_POLL_URL
• WECHAT_CODEX_WECHAT_REPLY_URL
• WECHAT_CODEX_WECHAT_API_TOKEN

Distribution

The intended end-state is:

npm install -g wechat-codex
wechat-codex setup
wechat-codex service start

The release flow is now:

• push tag vX.Y.Z
• GitHub Actions builds per-platform Rust binaries
• release archives are uploaded to GitHub Releases
• the npm package is published to npm and downloads the right binary during postinstall

Local source installs still work, but the primary shipping path is now npm install -g wechat-codex.

Roadmap

• finish the real WeChat protocol adapter
• validate service install and long-running behavior on real machines
• tighten recovery semantics and supervisor behavior
• add richer status/audit inspection surfaces
• publish a clean first install experience
• ship complete operator and contributor documentation

Who This Is For

This project is for people who:

• already use WeChat as their everyday messaging layer
• want Codex to run locally, not behind a hosted abstraction
• care about inspectable state and system behavior
• prefer practical personal tools over “AI platform” marketing

Contributing

The project is still in the architecture-to-implementation phase, so the most useful contributions right now are:

• runtime correctness
• queue and recovery behavior
• safety model review
• service management
• docs and operator experience

If you want to contribute, read the current Rust design doc first:

• Rust rewrite design

License

MIT