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