# wechat-codex

[![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-rust%20rewrite-orange.svg)](#project-status)
[![Built for Codex CLI](https://img.shields.io/badge/built%20for-Codex%20CLI-10a37f.svg)](https://developers.openai.com/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.

[中文说明](README_zh.md)

## 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

```text
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:

```bash
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

```bash
cd rust
cargo build
```

### Format

```bash
cd rust
cargo fmt --check
```

### Test

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

## Local Dogfooding

### 1. Run setup once

```bash
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

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

### 3. Install it as a service

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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](docs/designs/rust-rewrite.md)

## License

[MIT](LICENSE)