Codex-YOLO

Prerequisites

• tmux (tested with 3.4)
• codex (OpenAI Codex CLI — installed from the standalone GitHub release or npm install -g @openai/codex)
• git 2.38+ (required for worktree mode — git merge-tree --write-tree)

Installation

One-liner (macOS, Linux, WSL, Termux):

command -v curl >/dev/null || { s=; [ "$(id -u)" != 0 ] && s=sudo; command -v apt-get >/dev/null && { $s apt-get update && $s apt-get install -y curl; } || command -v dnf >/dev/null && $s dnf install -y curl || command -v yum >/dev/null && $s yum install -y curl || command -v apk >/dev/null && $s apk add curl || command -v pacman >/dev/null && $s pacman -S --noconfirm curl || command -v pkg >/dev/null && pkg install -y curl || command -v brew >/dev/null && brew install curl; }; curl -fsSL https://raw.githubusercontent.com/codex-yolo/codex-yolo/refs/heads/main/install.sh | bash && export PATH="${CODEX_YOLO_BIN_DIR:-$HOME/.local/bin}:${CODEX_YOLO_HOME:-$HOME/.codex-yolo}/bin:$PATH"

This clones to ~/.codex-yolo and symlinks the binary into ~/.local/bin. If ~/.local/bin is not writable, the installer falls back to ~/.codex-yolo/bin; you can also set CODEX_YOLO_BIN_DIR to choose a writable bin directory. It also installs git, tmux, curl, and codex if they are missing. Codex CLI is installed from the standalone GitHub release first, with npm as a fallback. Re-running the one-liner upgrades both codex-yolo and Codex CLI: if a newer stable Codex CLI release is published at openai/codex /releases/latest and the installed codex binary was placed by this script, it is overwritten with the new version (npm- or system-managed codex installs are left alone; set CODEX_YOLO_SKIP_CODEX_UPGRADE=1 to disable, or CODEX_YOLO_CODEX_VERSION=rust-v0.X.Y to pin a specific tag). Override the install location with CODEX_YOLO_HOME:

CODEX_YOLO_HOME="$HOME/my/path"; command -v curl >/dev/null || { s=; [ "$(id -u)" != 0 ] && s=sudo; command -v apt-get >/dev/null && { $s apt-get update && $s apt-get install -y curl; } || command -v dnf >/dev/null && $s dnf install -y curl || command -v yum >/dev/null && $s yum install -y curl || command -v apk >/dev/null && $s apk add curl || command -v pacman >/dev/null && $s pacman -S --noconfirm curl || command -v pkg >/dev/null && pkg install -y curl || command -v brew >/dev/null && brew install curl; }; curl -fsSL https://raw.githubusercontent.com/codex-yolo/codex-yolo/refs/heads/main/install.sh | CODEX_YOLO_HOME="$CODEX_YOLO_HOME" bash && export PATH="${CODEX_YOLO_BIN_DIR:-$HOME/.local/bin}:$CODEX_YOLO_HOME/bin:$PATH"

Local install (from a cloned repo; no network access needed if Codex CLI is already installed):

git clone https://github.com/codex-yolo/codex-yolo.git ~/.codex-yolo
cd ~/.codex-yolo
./install.sh --local

Manual install:

git clone https://github.com/codex-yolo/codex-yolo.git ~/.codex-yolo
ln -s ~/.codex-yolo/codex-yolo ~/.local/bin/codex-yolo

Then run from any project directory:

cd /path/to/your/project
codex-yolo "fix the tests" "update docs"

The tool runs agents in whatever directory you invoke it from (or the -d/--dir path if specified).

Quick start

```bash

Options

-s, --session NAME    Custom tmux session name (default: codex-yolo-<timestamp>)
-d, --dir PATH        Working directory for agents (default: current directory)
-m, --model MODEL     Model to use (e.g., o4-mini, o3, gpt-4.1)
-p, --poll SECONDS    Approver poll interval (default: 0.3)
-f, --file FILE       Read a multiline prompt from a text file
-c, --command STRING  Slash command to run in the control pane after launch
                      (e.g. "/loop 10m /plan ...", "/queue [...]", "/help").
                      Must start with '/'. Multi-line strings are sent as a paste.
                      Works with --resume to inject into an existing session.
-r, --resume          Re-attach to an existing yolo session
--permissions PROFILE Set Codex /permissions profile (default: full-access when allowed, else auto-review)
--no-codex-sandbox    Disable Codex sandboxing (for externally sandboxed containers)
--force-codex-sandbox Require Codex sandboxing; do not auto-fallback when unsupported
-h, --help            Show help

Worktree options:
-w, --worktree          Run each agent in its own git worktree
--base-branch BRANCH    Base branch for worktrees (default: current branch)
--no-merge              Skip auto-merge after agents complete
--no-cleanup            Keep worktrees after merge
--conflict-poll SECS    Conflict detection interval (default: 5)

install.sh options:
--local               Install from the local repo without pulling from GitHub

By default, codex-yolo probes codex sandbox linux true once. In containers where bubblewrap fails with namespace permission errors, codex-yolo creates a temporary fake bwrap earlier in PATH and launches agents without Codex sandboxing. The fake bwrap executes the command after bubblewrap's -- separator directly, so it should only be used inside an externally isolated container. Use --force-codex-sandbox to require the real sandbox and surface failures instead.

For Codex /permissions, codex-yolo defaults to Full Access when the active Codex requirements allow it. If Full Access is disabled by requirements, it uses Auto-review (codex-auto-review). In containers where the Codex sandbox is unavailable and codex-yolo has to rely on external isolation, the auto default also uses Auto-review. Override this with `--permissions full-access, --permissions auto-review, or --permissions none`. For standard interactive Auto-review sessions, codex-yolo also reconciles the TUI once at startup so /permissions shows Auto-review (current).

Worktree pipeline

When --worktree is enabled, three additional components run alongside the approver:

1. Worktree manager (lib/worktree-manager.sh) creates a branch and git worktree per agent in <repo>-worktrees/<session>/.
2. Conflict daemon (lib/conflict-daemon.sh) polls every --conflict-poll seconds and runs git merge-tree --write-tree across branch pairs. Conflicts are logged to the audit log.
3. Merge resolver (lib/merge-resolver.sh) waits for codex exec agents to finish, auto-commits uncommitted changes, merges branches into the base branch, and starts a Codex resolver task if a merge conflict occurs.