Unofficial mobile handoff for Codex TUI sessions.
Codoxear runs a small web server on your computer and exposes a phone-friendly UI for continuing the same live Codex TUI session from mobile. Your environment stays local (filesystem, tools, credentials). The phone is a view/controller.
Name: "codoxear" = "codex dogear" (dog-ear a page so you can pick up where you left off), meaning you can seamlessly continue the same work from different devices.
Not affiliated with OpenAI. "Codex" is referenced only for compatibility with the Codex CLI TUI.
Supported:
- Linux (uses
/proc, PTYs) - macOS (uses
lsof/pgrep, PTYs)
Not supported:
- Windows (no POSIX PTY/termios model; use WSL2 if you want a Linux environment)
Requires Python 3.10+.
Install Codoxear (installs codoxear-server and codoxear-broker):
python3 -m pip install .
-
Create
.env:- Copy
.env.exampleto.env - Set
CODEX_WEB_PASSWORD - Codoxear reads
.envfrom your current working directory
- Copy
-
Start the server:
codoxear-server- Default bind:
::(IPv6, usually reachable on LAN) - Default port:
8743
-
Add a separate
codoxwrapper for brokered sessions (zsh/bash function, not an alias):Never wrap or replace
codex()itself. Web-owned sessions launchcodexinternally, so wrappingcodex()to callcodoxear-brokercan recurse back into the broker and create an unbounded session-spawn loop.Add to
~/.zshrcor~/.bashrc:codox() { codoxear-broker -- "$@" }
Restart your shell or
sourceyour rc file. -
Use
codoxinstead ofcodexwhen you want the terminal session to be registered with Codoxear. Leave plaincodexunwrapped. -
On your phone, open
http://<your-computer>:8743, enter the password, and select the session. -
(Optional) Enable Harness mode for a session:
- Click the Harness icon in the top bar, toggle it on, tune cooldown minutes and injection count, and edit the optional extra request.
- Harness runs in the server process (not the browser tab), so it continues even if you close the web page.
- Settings are per session; each injection decrements the remaining count and harness turns itself off at zero. Enabled sessions show a
harnessbadge in the sidebar.
- Desktop Linux: start Codex in your GUI terminal emulator, then continue the same live TUI session on your phone or a laptop browser.
- Headless Linux: start Codex inside
tmux, then attach from your phone or a laptop browser. This avoids using a mobile terminal emulator for TUI interaction (for example Termius). - Web-owned sessions: start a new Codex session from the Codoxear UI, use it from mobile, and kill it from the UI when finished.
- Web-owned tmux sessions: start a new Codex session from the Codoxear UI with
Create in tmuxenabled to run it inside tmux sessioncodoxearfor shell-side observability.
Codoxear shows three kinds of sessions:
- Terminal-owned: sessions started from your local terminal via
codox(the broker wrapper). They are markedTin the UI. - Web-owned: sessions started from the Codoxear UI ("New session"). They are marked
Win the UI. - Web-owned tmux: sessions started from the Codoxear UI with
Create in tmuxenabled. They are marked with the tmux split-pane icon in the UI and run under tmux sessioncodoxear.
The current UI offers Delete for all session kinds. Delete sends a shutdown request to the underlying broker, so deleting a terminal-owned session also stops the corresponding terminal session.
If you start a web-owned session and later want to continue it in your terminal while keeping it registered with Codoxear, use codox resume. Use plain codex only for sessions that should stay outside Codoxear.
Codoxear cannot drive Codex confirmation prompts in default mode or plan mode from the browser UI.
For full remote interaction, run Codex in YOLO mode so confirmations do not block on interactive terminal prompts.
Codex does not always materialize (open) the new rollout-*.jsonl file immediately after /new. Codoxear tracks the active rollout by scanning the Codex process tree for open rollout-log file descriptors, so the UI may show the session as pending until the first prompt is sent and the rollout file is created/opened.
This project intentionally keeps security out of scope. It provides password gating only and does not provide TLS.
Assume anyone who can reach the port can:
- observe traffic (including the password)
- modify traffic
Use your own secure channel (VPN, SSH port-forward, reverse proxy with TLS) if you need network security.
Set these in .env (or in the process environment):
CODEX_WEB_PASSWORD(required)CODEX_WEB_HOST(default::)CODEX_WEB_PORT(default8743)CODEX_WEB_URL_PREFIX(default empty). Example:/codoxearserves the UI at/codoxear/and the API under/codoxear/api/*.CODEX_HOME(default~/.codex)CODEX_BIN(defaultcodex)CODEX_WEB_COOKIE_TTL_SECONDS(default2592000, 30 days)CODEX_WEB_COOKIE_SECURE(default0; set to1behind HTTPS)CODEX_WEB_HARNESS_SWEEP_SECONDS(default2.5)CODEX_WEB_QUEUE_SWEEP_SECONDS(default1.0)CODEX_WEB_QUEUE_IDLE_GRACE_SECONDS(default10.0)CODEX_WEB_DISCOVER_MIN_INTERVAL_SECONDS(default1.0)CODEX_WEB_METRICS_WINDOW(default256)CODEX_WEB_FILE_READ_MAX_BYTES(default2097152)CODEX_WEB_FILE_HISTORY_MAX(default20)CODEX_WEB_GIT_DIFF_MAX_BYTES(default819200)CODEX_WEB_GIT_DIFF_TIMEOUT_SECONDS(default4.0)CODEX_WEB_GIT_CHANGED_FILES_MAX(default400)CODEX_WEB_FD_POLL_SECONDS(default1.0) - how often the broker scans/procto detect the activerollout-*.jsonl
Runtime state is stored under ~/.local/share/codoxear (legacy ~/.local/share/codex-web is no longer used).
MIT, see LICENSE.