codex-tmux-scroll is a patched Codex CLI whose mouse wheel opens a static history view inside tmux

The wheel stops walking prompt history and opens a static scrollback view

Inside tmux, the mouse wheel has a job of its own, so Codex never got to use it for reading back a conversation. That is the gap this build fills. Scroll the wheel and it moves through the Codex conversation instead of triggering prompt history navigation, and the view you land in is static: fresh output from the agent does not drag the content you are reading upward while you read it. A percentage indicator shows where you are in the history while scrolling, and the input prompt stays visible at the bottom the whole time, so you can read and still see what you would type next.

Two details make it usable rather than merely different. Scrolling back to the bottom does not collapse the viewport, it keeps the full history view plus the prompt. And double-clicking the prompt area jumps straight back to the latest output, which is the escape hatch when you have lost your place. Mouse drag selection also works inside the history, so you can select text with the left button and release to copy it to the clipboard. None of this touches the agent itself. Aside from these tmux interaction changes it behaves like the normal `codex` command, and your existing local auth, config, AGENTS.md, and project workflows keep working.

Without set -g mouse on in tmux, none of the wheel behaviour happens

The project changes what tmux hands the mouse to, so tmux has to be forwarding it in the first place. That is a one-line change to your tmux configuration:

set -g mouse on

Set it once and new tmux sessions pick it up automatically. This is the piece that looks broken when you skip it, because with mouse forwarding off, tmux keeps the wheel for its own scrollback and copy-mode behaviour and Codex never sees the events this build depends on. Worth being precise about the division of labour: tmux decides whether the terminal reports mouse events, and this build decides what Codex does with them. It does not edit your tmux config for you, and it does not detect or warn about a missing setting.

Once the setting is in place, the launch sequence is ordinary. Start or attach a session, move into the project, and run the wrapper:

tmux new -s work
cd /path/to/project
codex-tmux-scroll

Arguments pass straight through to the bundled Codex CLI, so the launch forms you already type keep working, including `codex-tmux-scroll resume`, `codex-tmux-scroll --dangerously-bypass-approvals-and-sandbox`, and that flag combined with `resume`. That pass-through is the reason this can be treated as a drop-in replacement inside a tmux workflow rather than a separate tool with its own command language.

The installer pipes curl to bash, writes two files, and leaves codex alone

Install is a single pipeline, Linux x86_64 only:

curl -fsSL https://raw.githubusercontent.com/GuanhuaYe/codex-tmux-scroll/main/install.sh | bash

The installer writes exactly two paths: a binary at `~/.local/lib/codex-tmux-scroll/codex`, which is the rebuilt Codex binary, and a wrapper at `~/.local/bin/codex-tmux-scroll` that you invoke instead of `codex`. What it deliberately does not do is replace your global `codex` command, so the two can sit side by side on the same machine and you choose per session which one runs. For anyone already using Codex outside tmux, that separation is the difference between adopting this and having to uninstall it.

There is a consequence to the curl-into-bash shape, though. Trusting this path means trusting whatever `main` currently serves, which is a moving ref rather than a pinned release artifact, and there is no checksum step in the documented install path. The build itself is stricter than the install: a release archive is published alongside a `.sha256` file next to the tarball, so if you would rather verify what you are running, download those artifacts and compare the hash yourself before wiring the wrapper into your shell path. Updating is the same command again, since rerunning the installer pulls the latest release.

The whole tmux change is one patch file, not a vendored copy of Codex

The repository does not vendor the Codex source tree, and that decision shapes everything about how it is maintained. The tmux-specific work lives as a single patch, `patches/codex-tmux-scroll-v0.139.0.patch`, and the tracked tree is correspondingly small: install.sh, patches/, scripts/, legal/, README.md, LICENSE, and a .github directory. Upgrading to a new Codex CLI means rebasing that one patch onto the new upstream tag, rebuilding the binary, and publishing a new GitHub release.

The build is driven by three environment variables. `CODEX_UPSTREAM_URL` points at the upstream Codex git URL, `CODEX_UPSTREAM_REF` selects the upstream tag, and the build script by default picks the patch file whose name matches that ref, so `rust-v0.139.0` resolves to the v0.139.0 patch. A third variable, `CODEX_RUST_TOOLCHAIN`, exists because the build otherwise inherits whichever Rust toolchain the upstream source tree selects, and you need a way to force a specific one.

The practical effect is version coupling. As shipped, the current base is Codex CLI 0.139.0 and the only supported platform is Linux x86_64, which is visible in the release artifacts too: `dist/codex-tmux-scroll-x86_64-unknown-linux-gnu.tar.gz`, its `.sha256`, and install.sh. A reader on macOS or on aarch64 Linux finds no build for their platform here, and a reader on a newer Codex finds no release rebased onto it.

When the patch stops applying, git apply --reject hands you the hunks to fix

This is where the maintenance cost lands, and the project is straightforward about it. To move to a newer upstream, first test whether the existing patch still applies by pointing the build at the new tag while keeping the old patch file:

CODEX_UPSTREAM_URL=<codex-cli-upstream-git-url> \
CODEX_UPSTREAM_REF=rust-v0.140.0 \
CODEX_TMUX_SCROLL_PATCH_FILE=patches/codex-tmux-scroll-v0.139.0.patch \
./scripts/build-from-source.sh

If it builds and the tmux behaviour still works, the fix is a copy: `cp` the old patch to the new version's name. If it no longer applies, the path is longer. A shallow clone of the new tag goes into `worktrees/codex-rust-v0.140.0`, the patch is applied with `git apply --reject`, and every hunk that fails to apply is written out as a reject file for a human to resolve:

git clone --depth 1 --branch rust-v0.140.0 \
  <codex-cli-upstream-git-url> \
  worktrees/codex-rust-v0.140.0
cd worktrees/codex-rust-v0.140.0
git apply --reject ../../patches/codex-tmux-scroll-v0.139.0.patch

After fixing the rejected hunks you build with `cargo build -p codex-cli --release` and regenerate the patch with `git diff --binary`, excluding `codex-rs/Cargo.lock` so the upstream lockfile does not leak into the diff. None of this is automated. A rebase is manual work, which is the honest cost of not vendoring.

Release tags encode the upstream version, so the tmux counter is what moves

Tag names follow a fixed pattern, `v<upstream-codex-version>-tmux.<patch-version>`, which makes the dependency legible at a glance: `v0.139.0-tmux.1`, then `v0.140.0-tmux.1` and `v0.140.0-tmux.2`. The counter after `tmux` counts this project's own iterations, not Codex releases, so two tags can share an upstream base and differ only in how many times the tmux behaviour was patched. All three existing tags, `v0.139.0-tmux.1`, `.2`, and `.3`, were published on the same day, 10 June 2026, which is also the last push to the default branch. So the visible history is one afternoon of iterating on a single Codex base rather than a steady stream of upstream tracking.

Packaging separates building from publishing. `./scripts/package-release.sh` takes the upstream URL and ref and produces the archive; if you have already built and tested a binary, `CODEX_TMUX_SCROLL_BINARY_PATH` lets you package that one instead of rebuilding. The release then carries the tarball, its sha256, and install.sh, and the installer is written to fetch the latest release, which is why updating is just rerunning the original command.

Licensing is Apache-2.0 with third-party notices kept in `legal/THIRD_PARTY_NOTICES.md`. That is the right arrangement for a redistributed Codex build, since it carries upstream code, and it means anyone redistributing a patched binary has a clear obligation to carry those notices along.

Editorial conclusion

Take it if you already live in tmux, run Codex there daily, and keep tripping over the wheel navigating prompt history instead of reading back what the agent just did. Skip it if you are on macOS, on a non-x86_64 Linux box, or if you would rather wait for the change upstream. Verify two things before adopting: that your Codex base is still 0.139.0 or that a release has been rebased onto your version, and that `set -g mouse on` is in your tmux config, because without it nothing about the wheel changes. Then rerun the installer to move between releases, since it always pulls the latest one.

Frequently asked questions

Official sources

1. GuanhuaYe/codex-tmux-scroll on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases