README.md

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