--- 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 ```bash git clone https://huggingface.co/yitongl/codex_exec cd codex_exec chmod +x codex_auto_run.py ``` ## Start a new session ```bash ./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: ```bash ./codex_auto_run.py -C ~/code/my_project --prompt-file task.md ``` ## Detach and reattach Start without attaching: ```bash ./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: ```bash 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: ```bash ./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: ```bash ./codex_auto_run.py \ --resume SESSION_ID \ -C ~/code/my_project \ -p "Continue from the previous result." ``` Open Codex's interactive session picker: ```bash ./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 `--`: ```bash ./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: ```bash ./codex_auto_run.py --status ``` Stop the watcher: ```bash ./codex_auto_run.py --stop-daemon ``` Start only the watcher: ```bash ./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`](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: ```bash 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.