Codex-Work

KO | EN

gitlite — search

#hacktoberfest #react #typescript #go #linux #docker #nodejs #macos #java #awesome #awesome-list #vue #pytorch #ios

(★ 1)

Codex Works - a hardened, cross-platform Codex app-server UI for Linux, Windows and Android, focused on security, long-running stability and native mobile use. Pascal (MC Pasi) — An independent evolution of CodexUI. We call it Codex Works.

Codex-Work 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🔥 Codex Works

### 🚀 Run Codex Works Anywhere: Linux, Windows, or Android 🚀

[![npm](https://img.shields.io/npm/v/codex-works?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/codex-works)
[![platform](https://img.shields.io/badge/Platform-Linux%20%7C%20Windows%20%7C%20Android-blue?style=for-the-badge)](https://raw.githubusercontent.com/Mcpasi/Codex-Work/main/)
[![node](https://img.shields.io/badge/Node-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
[![license](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://raw.githubusercontent.com/Mcpasi/Codex-Work/main/LICENSE)

Apk Download: [itch.io/pascalmcpasi/codex-works](https://pascalmcpasi.itch.io/codex-works)
<br>
Repository: [github.com/Mcpasi/Codex-Work](https://github.com/Mcpasi/Codex-Work)

> **Codex Works in your browser. No drama. One command.**
>  
> **Yes, that is your Codex desktop app experience exposed over web UI. Yes, it runs cross-platform.**

```text
 ██████╗ ██████╗ ██████╗ ███████╗██╗  ██╗██╗   ██╗██╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝╚██╗██╔╝██║   ██║██║
██║     ██║   ██║██║  ██║█████╗   ╚███╔╝ ██║   ██║██║
██║     ██║   ██║██║  ██║██╔══╝   ██╔██╗ ██║   ██║██║
╚██████╗╚██████╔╝██████╔╝███████╗██╔╝ ██╗╚██████╔╝██║
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═╝
```

---
<img width="1366" height="900" alt="image" src="https://github.com/user-attachments/assets/1a3578ba-add8-49a2-88b4-08195a7f0140" />

## 🤯 What Is This?
**Codex Works** (`codex-works` on npm and the command line) is a lightweight bridge that gives you a browser-accessible UI for Codex app-server workflows.

You run one command. It starts a local web server. You open it from your machine, your LAN, or wherever your setup allows.

**TL;DR 🧠: Codex app UI, unlocked for Linux, Windows, and Termux-powered Android setups.**

---

## ⚡ Quick Start
> **The main event.**

```bash
# 🔓 Run instantly (recommended)
npx codex-works

# 🌐 Then open in browser
# http://localhost:5900
```

Run with `--tunnel` when you want Codex Works to start:

```bash
cloudflared tunnel --url http://localhost:<port>
```

Startup prints the tunnel URL and terminal QR code without embedding any secret. It prints only the path to the protected access-token JSON; the token value itself never appears in startup output. Without an explicit tunnel flag, tunnel startup follows local Tailscale detection; use `--no-tunnel` to disable it.

When a reverse proxy terminates TLS, explicitly trust each proxy's backend peer IP so Codex Works can use its protocol metadata:

```bash
npx codex-works --trusted-proxy 127.0.0.1
# Repeat --trusted-proxy <ip> for additional proxy peers.
```

The option accepts exact IPv4 or IPv6 literals only—not hostnames, ports, CIDRs, or wildcards. Codex Works ignores `X-Forwarded-Proto` from every other socket peer. The trusted proxy must preserve the public `Host` and replace any client-supplied `X-Forwarded-Proto` with its authoritative `http` or `https` value. For the built-in local Cloudflare tunnel, start with `--tunnel --trusted-proxy 127.0.0.1`.

If you are using a provider or AI gateway that is already authenticated and do not want Codex Works to force `codex login` during startup, use:

```bash
npx codex-works --no-login
```

### Codex Works access-token safety

Untrusted browser access is protected by a 256-bit random token stored at `$CODEX_HOME/codex-works-access.json` (normally `~/.codex/codex-works-access.json`). Codex Works creates it once with `0600` permissions, rejects symbolic links and malformed or weak-format values, and never accepts the secret through CLI arguments, URLs, QR codes, logs, browser storage, feedback data, or project ZIPs.

The JSON is intentionally user-controlled. To find it or rotate it safely:

```bash
codex-works access-token path
codex-works access-token rotate
```

You may replace `accessToken` manually with another `cwx_` token containing exactly 32 cryptographically random bytes encoded as 43 base64url characters. Restart every running Codex Works server afterward. A manual change or secure rotation invalidates all earlier browser sessions; the session file contains only SHA-256 verifiers, is bounded to 64 seven-day sessions, and is also kept at `0600`.

Remote token sign-in requires direct HTTPS, HTTPS reported by an explicitly trusted proxy, or a loopback backend hop. A remote client cannot make an HTTP request secure by sending `X-Forwarded-Proto: https`; the header is ignored unless the socket peer matches a repeatable `--trusted-proxy <ip>` entry. Direct localhost and Tailscale peers retain their separate trusted-network bypass. `--no-auth` exists only as an explicit opt-out for controlled development or test environments. The retired password CLI options, password login payload, one-click secret URL, password file, and cleartext session store are no longer supported; legacy files are removed automatically.

This access-token authentication design, the trusted reverse-proxy protocol boundary, and the retirement of the previous password system are project-specific security work originated and specified by **Pascal(Mc Pasi)**.

### Codex credential safety

Codex file-backed login state is kept only at `$CODEX_HOME/auth.json`, which defaults to `~/.codex/auth.json`. Set `CODEX_HOME` only to an absolute directory outside every project you open. If upstream Codex is configured to use the operating-system keyring, no `auth.json` mirror is created.

Codex Works does not store Codex access, refresh, or ID tokens in `localStorage`, `sessionStorage`, IndexedDB, project files, account metadata, or project ZIPs. Older `$CODEX_HOME/accounts/*/auth.json` snapshots are removed, and the retired account-import/copy helpers no longer duplicate credentials. To change accounts, run Login again so Codex replaces the single active credential.

The browser-assisted callback is transient, is sent only to the local server, and account/login responses are marked `no-store`. The separate Codex Works access session uses a hashed server-side verifier and an HttpOnly cookie; neither is a Codex OAuth token. See the official [Codex authentication and credential-storage documentation](https://learn.chatgpt.com/docs/auth).

### Browser-origin safety

The realtime bridge accepts `/codex-api/ws` only when the WebSocket upgrade includes a valid same-origin `Origin` header. Its HTTP(S) scheme and host/port must match the requested server origin. HTTPS reported through `X-Forwarded-Proto` counts only when the socket peer matches an exact `--trusted-proxy <ip>` entry; otherwise the header is ignored, so a remote client cannot forge a secure same-origin request. Missing, `null`, malformed, and foreign origins receive `403` before local-network/access-session trust is considered and before bridge notifications are subscribed. Trusted reverse proxies must preserve the public `Host` and overwrite `X-Forwarded-Proto` with an accurate value.

### 24/7 WebSocket lifecycle

The realtime bridge keeps one upstream notification subscription for all currently connected WebSocket clients and serializes each notification once. A single 30-second, unref'ed Ping/Pong timer runs only while clients exist; a peer that misses a full heartbeat cycle is terminated without affecting responsive peers. Incoming messages are capped at 64 KiB because the channel is notification-only, and a client whose outbound backlog exceeds 8 MiB is disconnected before it can grow without bound.

The idempotent bridge disposer removes HTTP listeners, clears the timer and subscription, and terminates every upgraded client. Both the packaged CLI and Vite development server invoke it before waiting for HTTP shutdown, avoiding the Node.js behavior where upgraded sockets can hold `server.close()` open indefinitely. After a successful browser handshake, later reconnects start again at the initial backoff instead of accumulating delay across a 24/7 session.

### Linux 🐧
```bash
node -v   # should be 18+
npx codex-works
```

### Windows 🪟 (PowerShell)
```powershell
node -v   # 18+
npx codex-works
```

### Native Android APK 📱

Codex Works 1.0.6 can be built as a self-contained ARM64 Android application named **Codex Works**. It embeds the frontend, Node server, Codex app-server executable, Android ripgrep, and a real PTY terminal, then serves the WebView only through `127.0.0.1:5900`.

```bash
corepack pnpm@10.28.1 run build:android-apk
# output/android-apk/Codex Works.apk
```

The initial APK supports Android 10+, ARM64-v8a, and 4 KiB-page devices. The on-device build uses Termux's Android clang plus an ARM64 Ubuntu/Debian PRoot with JDK 17 and APK packaging tools. See the complete [Android APK build, signing, installation, security, and troubleshooting guide](./apps/codex-works-apk/README.md).

This is a new Codex Works application under `apps/codex-works-apk/`, not a restoration of the retired AnyClaw Android distribution.

### Termux (Android) 🤖
```bash
pkg update && pkg upgrade -y
pkg install nodejs -y
npx codex-works
```

Android background requirements:

1. Keep `codex-works` running in the current Termux session (do not close it).
2. In Android settings, disable battery optimization for `Termux`.
3. Keep the persistent Termux notification enabled so Android is less likely to kill it.
4. Optional but recommended in Termux:
```bash
termux-wake-lock
```
5. Open the shown URL in your Android browser. If the app is killed, return to Termux and run `npx codex-works` again.

---

## iPhone / iPad via Tailscale Serve

If you want to use Codex Works from iPhone or iPad Safari, serving it over HTTPS is recommended.

A practical private setup is to run Codex Works locally and publish it inside your tailnet with Tailscale Serve:

```powershell
npx codex-works --no-tunnel --port 5900
tailscale serve --bg 5900
```

Then open:

```text
https://<your-machine>.<your-tailnet>.ts.net
```

This setup worked well in practice for:

- iPhone Safari access
- Add to Home Screen
- the built-in dictation / transcription feature in the app
- viewing the same projects and conversations from the Windows host

Notes:

- Tailscale Serve keeps access private to your tailnet
- on iOS, HTTPS / secure context appears to be important for mobile browser access and dictation
- some minor mobile Safari CSS issues may still exist, but they do not prevent normal use
- depending on proxying details, authentication behavior may differ from direct remote access
- if conversations created in the web UI do not immediately appear in the Windows app, restarting the Windows app may refresh them

---

## ✨ Features
> **The payload.**

- 🚀 One-command launch with `npx codex-works`
- 🌍 Cross-platform support for Linux, Windows, and Termux on Android
- 🖥️ Browser-first Codex Works flow on `http://localhost:5900`
- 🌐 LAN-friendly access from other devices on the same network
- 🧪 Remote/headless-friendly setup for server-based Codex usage
- 🔌 Works with reverse proxies and tunneling setups
- ⚡ No global install required for quick experimentation
- 🧠 GPT-5.6 Sol thinking controls include Max and Ultra reasoning levels
- 🎙️ Built-in hold-to-dictate voice input with transcription to composer draft
- 🤖 Optional Telegram bot bridge: send messages to bot, forward into mapped thread, send assistant reply back to Telegram
- 💾 Project portability: export a project as a ZIP from project or thread menus, including matching Codex chat JSONL history under `.codex-project/chats/`
- 📦 Project import: restore exported project ZIPs from the browser via `Import Project`
- 🔁 Imported chats are rewritten for the destination `CODEX_HOME`, project path, and currently selected provider/model so they can be resumed in the new environment
- ⚙️ Project ZIP performance: exports stream ZIP bytes with response backpressure handling and skip generated/git-ignored folders; imports still buffer the selected ZIP once because the browser upload arrives as a single file

### 24/7 app-server cache policy

The bridge bounds idle thread-scoped caches to 128 recent threads with a one-hour inactivity TTL and a 60-second sweep. Turn-page reads retain their existing 30-second TTL, stream history is capped at 400 events per thread, and completed fallback items are capped at 1,000 per thread. Active turns and in-flight coalesced thread reads are protected from LRU/TTL eviction; they may exceed the idle limit temporarily and are reconsidered after completion. `dispose()` clears every thread cache, promise registry, activity marker, and sweep timer.

Operators can inspect aggregate, non-secret counters at `GET /codex-api/cache-metrics`, including entry counts, hit/miss/coalescing totals, TTL/LRU/dispose evictions, protected threads, and temporary over-capacity state. Thread IDs and cached payloads are not exposed by this endpoint.

### Telegram Bot Bridge (Optional)

Set these environment variables before starting Codex Works:

```bash
export TELEGRAM_BOT_TOKEN="<your-telegram-bot-token>"
export TELEGRAM_ALLOWED_USER_IDS="<your-telegram-user-id>,<optional-second-id>"
export TELEGRAM_DEFAULT_CWD="$PWD" # optional, defaults to current working directory
npx codex-works
```

`TELEGRAM_ALLOWED_USER_IDS` is required for safe access. Only allowlisted Telegram user IDs can use the bridge. If no allowed user IDs are configured, incoming Telegram messages are rejected.

To find your Telegram user ID:

1. Send a message to your bot.
2. Run `curl "https://api.telegram.org/bot<your-telegram-bot-token>/getUpdates"`.
3. Read `message.from.id` from the returned update payload.

Bot commands:

- `/start` show quick help and thread picker
- `/threads` list recent threads and pick one
- `/newthread` create and map a new Codex thread for this Telegram chat
- `/thread <threadId>` map current Telegram chat to an existing thread
- `/current` show currently connected thread for this chat
- `/history` show recent history for current thread
- `/status` show bridge/mapping status
- `/whoami` show your Telegram user/chat IDs and authorization state
- `/help` show command reference

Outgoing assistant messages are sent with Telegram `parse_mode=HTML` for formatting, with automatic plain-text fallback if HTML delivery fails.

---

## 🧩 Recent Product Features (from main commits)
> **Not just launch. Actual UX upgrades.**

- 🗂️ Searchable project picker in new-thread flow
- ➕ "Create Project" button next to "Select folder" with browser prompt
- 📌 New projects get pinned to top automatically
- 🧠 Smart default new-project name suggestion via server-side free-directory scan (`New Project (N)`)
- 🔄 Project order persisted globally to workspace roots state
- 🧵 Optimistic in-progress threads preserved during refresh/poll cycles
- 📱 Mobile drawer sidebar in desktop layout (teleported overlay + swipe-friendly structure)
- 🎛️ Skills Hub mobile-friendly spacing/toolbar layout improvements
- 🪟 Skill detail modal tuned for mobile sheet-style behavior
- 🧪 Skills Hub event typing fix for `SkillCard` select emit compatibility
- 🎙️ Voice dictation flow in composer (`hold to dictate` -> transcribe -> append text)

---

## 🌍 What Can You Do With This?

| 🔥 Use Case | 💥 What You Get |
|---|---|
| 💻 Linux workstation | Run Codex Works in a browser without depending on the desktop shell |
| 🪟 Windows machine | Launch web UI and access from Chrome/Edge quickly |
| 📲 Native Android APK | Run the embedded ARM64 Node, Codex app-server, ripgrep, WebView, and PTY as Codex Works |
| 📱 Termux on Android | Start service in Termux and control from mobile browser |
| 🧪 Remote dev box | Keep Codex process on server, view UI from client device |
| 🌐 LAN sharing | Open UI from another device on same network |
| 🧰 Headless workflows | Keep terminal + browser split for productivity |
| 🔌 Custom routing | Put behind reverse proxy/tunnel if needed |
| ⚡ Fast experiments | `npx` run without full global setup |

---

## 🖼️ Screenshots

### Skills Hub
![Skills Hub](https://raw.githubusercontent.com/Mcpasi/Codex-Work/main/docs/screenshots/skills-hub.png)

### Chat
![Chat](https://raw.githubusercontent.com/Mcpasi/Codex-Work/main/docs/screenshots/chat.png)

### Mobile UI
![Skills Hub Mobile](https://raw.githubusercontent.com/Mcpasi/Codex-Work/main/docs/screenshots/skills-hub-mobile.png)
![Chat Mobile](https://raw.githubusercontent.com/Mcpasi/Codex-Work/main/docs/screenshots/chat-mobile.png)

---

## 🏗️ Architecture

```text
┌─────────────────────────────┐
│  Browser (Desktop/Mobile)   │
└──────────────┬──────────────┘
               │ HTTP/WebSocket
┌──────────────▼──────────────┐
│        Codex Works          │
│  (Express + Vue UI bridge)  │
└──────────────┬──────────────┘
               │ RPC/Bridge calls
┌──────────────▼──────────────┐
│      Codex App Server       │
└─────────────────────────────┘
```

The large runtime entry points now keep stable facades while auth, thread-archive recovery, provider-model discovery, pure desktop thread state, and route synchronization live in focused modules. See [Large-module architecture](./documentation/MODULE_ARCHITECTURE.md) for the responsibility map and compatibility guarantees. This behavior-preserving decomposition was originated and specified by **Pascal(Mc Pasi)** and remains part of Codex Works `1.0.6`.

---

## 🎯 Requirements
- ✅ Node.js `18+`
- ✅ Codex app-server environment available
- ✅ Browser access to host/port
- ✅ Microphone permission (only for voice dictation)
- ✅ APK build only: ARM64 Termux clang, JDK 17, `apksigner`, `zipalign`, and Android 10+ with 4 KiB pages

### Release metadata

The current release identity is `codex-works@1.0.6`. `publish.sh` publishes the version already declared in `package.json`; it does not silently increment it. Update the version intentionally before a later release. The obsolete AnyClaw APK workflow, separate `codex-works-android` publisher, and APK marketing page remain retired. A separate, newly implemented Codex Works 1.0.6 APK now lives under `apps/codex-works-apk/`; regular mobile-browser and Termux support also remains available through `codex-works`. This release direction, retirement boundary, and new native APK direction were originated and specified by **Pascal(Mc Pasi)**. The project repository is [Mcpasi/Codex-Work](https://github.com/Mcpasi/Codex-Work).

---

## 🐛 Troubleshooting

| ❌ Problem | ✅ Fix |
|---|---|
| Port already in use | Run on a free port or stop old process |
| `npx` fails | Update npm/node, then retry |
| Termux install fails | `pkg update && pkg upgrade` then reinstall `nodejs` |
| APK will not install silently from Termux | Open `Codex Works.apk` with Android's package installer or use an ADB/Shizuku-authorized shell |
| APK startup fails | Run `adb logcat -s CodexWorksNode`; confirm ARM64, Android 10+, current WebView, and a 4 KiB page size |
| Can’t open from other device | Check firewall, bind address, and LAN routing |

---

## 🤝 Contributing
Issues and PRs are welcome.  
Bring bug reports, platform notes, and setup improvements.

### Project-specific work and attribution

The GPT-5.6 Sol `Max`/`Ultra` thinking-level extension, Codex credential-storage hardening, 256-bit Codex Works access-token authentication with strict login-payload and aborted-request handling, legacy-password retirement, same-origin WebSocket bridge hardening, trusted reverse-proxy protocol hardening, 24/7 WebSocket lifecycle hardening, bounded 24/7 app-server caches, the behavior-preserving large-module decomposition for auth, archive recovery, provider models, thread state, and routes, Codex Works product/release identity, the Codex Works 1.0.6 release alignment and legacy AnyClaw Android-distribution retirement, the new Codex Works 1.0.6 native Android APK build/runtime/terminal boundary, and strengthened no-Git agent/validation workflow are project-specific contributions originated and specified by **Pascal(Mc Pasi)**. Their implementation scope and verification coverage are recorded in [PROJECT_CONTRIBUTIONS.md](./PROJECT_CONTRIBUTIONS.md).

This attribution supplements the upstream history. The MIT terms, existing upstream copyright notices, package authors, and upstream credits remain unchanged; [LICENSE](./LICENSE) carries a separate notice for project-specific contributions by **Pascal(Mc Pasi)**.

---

## ⭐ Star This Repo
If you believe Codex Works should be accessible from **any machine, any OS, any screen**, star this project and share it. ⭐

<div align="center">
Built for speed, portability, and a little bit of chaos 😏
</div>

---

Codex-Work

Codex-Work 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Codex-Work

Codex-Work 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README