Hugging Face's logo

yitongl
/
codex_exec

codex
tmux
automation
developer-tools
Model card Files
xet
 Community
codex_exec / README.md
yitongl's picture
yitongl
Document project-aware autorun aliases
20666a8
preview code
|
Raw
History Blame Contribute Delete
6.64 kB
metadata 
tags:
  - codex
  - tmux
  - automation
  - developer-tools

codex_exec

codex_exec is an unofficial launcher for the interactive OpenAI Codex TUI. It starts a real interactive codex session inside tmux and runs a small watcher that can confirm recognized approval dialogs automatically.

Despite the repository name, this is not codex exec and it does not turn Codex into a non-interactive subprocess. You can attach to the TUI, type follow-up messages, detach, reattach, and resume persisted Codex conversations normally.

The runtime is one self-contained Python script with no third-party Python dependencies.

Requirements

  • Linux. The watcher uses fcntl and /proc for locking and process identity checks.
  • Python 3.10 or newer.
  • tmux available on PATH.
  • The Codex CLI installed, authenticated, and available as codex on PATH (or supplied with --codex-binary).

The current implementation and tests were validated with Codex CLI 0.142.3. The watcher recognizes text rendered by the Codex TUI, so a future Codex release that changes approval wording or layout may require detector updates.

Important safety warning

By default, Codex still starts with on-request approvals and the workspace-write sandbox. However, the watcher automatically confirms recognized one-shot approval choices for:

  • shell commands;
  • file edits;
  • permission requests; and
  • network access requests.

This removes the human review normally provided by an approval prompt. A mistaken or prompt-injected Codex action may delete files, run untrusted commands, disclose accessible data over the network, or request broader permissions. The watcher is a convenience mechanism, not a security boundary. Use it only in a workspace whose contents and consequences you understand, keep important work under version control, and prefer a disposable or externally isolated environment for risky tasks.

The watcher does not automatically answer ordinary questions, enable a full-access screen, trust hooks, install plugins, approve MCP/app calls, or trust a directory unless the relevant explicit option is enabled.

--approve-mcp can approve app or MCP calls with external side effects. --auto-trust-directory bypasses Codex's initial directory-trust confirmation. --bypass is substantially more dangerous: it passes Codex's --dangerously-bypass-approvals-and-sandbox option and should only be used inside an environment that is already isolated outside Codex.

Installation 

git clone https://huggingface.co/yitongl/codex_exec
cd codex_exec
chmod +x codex_auto_run.py

Start a new session 

./codex_auto_run.py \
  -C ~/code/my_project \
  -p "Implement the requested change, run the tests, and summarize the result."

The launcher creates a uniquely named tmux session and normally attaches to it immediately. The printed startup information includes the exact command needed to reattach.

Use a UTF-8 prompt file when the task is long:

./codex_auto_run.py -C ~/code/my_project --prompt-file task.md

Detach and reattach

Start without attaching:

./codex_auto_run.py \
  --detach \
  -C ~/code/my_project \
  -p "Run the full task and verify the result."

Then attach with the session name printed by the launcher:

tmux attach -t codex-auto-YYYYMMDD-HHMMSS-PID-RANDOM

Inside tmux, press Ctrl-b d to detach without stopping Codex. Exiting Codex normally ends the tmux session unless --keep-dead-session was used. When no managed panes remain, the watcher exits after its idle timeout (120 seconds by default).

Resume a Codex conversation

Resume the most recent interactive conversation for a working directory:

./codex_auto_run.py \
  --resume-last \
  -C ~/code/my_project \
  -p "Continue the task and rerun the verification."

Resume a specific Codex session ID or name:

./codex_auto_run.py \
  --resume SESSION_ID \
  -C ~/code/my_project \
  -p "Continue from the previous result."

Open Codex's interactive session picker:

./codex_auto_run.py --resume -C ~/code/my_project

The picker form cannot be combined with -p or --prompt-file; select the conversation first and then type in Codex. Resuming starts a new tmux wrapper around a persisted Codex conversation. If the original tmux session is still running, simply reattach to that session instead.

Pass options to Codex

Place Codex-specific global options after --:

./codex_auto_run.py \
  -C ~/code/my_project \
  -p "Research and implement the task." \
  -- \
  --search \
  --model MODEL_NAME

The wrapper reserves -p for the initial or resumed-session follow-up prompt. Use --codex-profile PROFILE_NAME for a Codex profile.

No model is hardcoded by this repository. Without --model, Codex inherits the model selected by the user's Codex configuration and CLI defaults.

Some Codex options that conflict with wrapper-managed behavior, including Codex's own approval, sandbox, working-directory, full-auto, and bypass flags, are rejected. Use the wrapper's --sandbox, -C, and --bypass options instead.

Watcher controls

Show the watcher and managed-session status:

./codex_auto_run.py --status

Stop the watcher:

./codex_auto_run.py --stop-daemon

Start only the watcher:

./codex_auto_run.py --start-daemon

By default, private watcher state and logs are stored under ~/.runtime/codex-auto/. Only sessions created and registered by this wrapper are watched.

Run ./codex_auto_run.py --help for all tuning and safety options.

Optional shell aliases

LOCAL_SETUP.txt contains the current runx/rund Bash functions, project-relative tmux naming rules, usage examples, and the local codex-autorun skill location. The rund function expects a separate ~/claude_auto_run.py, which is not included in this repository.

Tests

The unit tests exercise approval-screen detection, argument validation, resume command construction, binary probing, tmux command construction, and daemon lifecycle safeguards without starting a real Codex session:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v test_codex_auto_run.py

A passing unit-test suite cannot guarantee compatibility with a future Codex TUI. Before relying on unattended operation after a Codex upgrade, observe a real low-risk session and verify that approvals are detected as intended.

Project status

This project is independent and unofficial. It is not an OpenAI product and is not endorsed or supported by OpenAI.