codex-tmux-scroll is a Codex CLI build for people who run Codex inside long tmux sessions.

It changes tmux mouse interaction: the mouse wheel opens a static conversation history view while the input prompt stays pinned at the bottom, mouse drag selection copies text from history, and double-clicking the prompt jumps back to the latest output. Aside from these tmux interaction changes, it behaves like the normal codex command.

Install

Linux x86_64:

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

After it finishes, use it directly:

codex-tmux-scroll

The installer writes:

  • binary: ~/.local/lib/codex-tmux-scroll/codex
  • wrapper: ~/.local/bin/codex-tmux-scroll

It does not replace your global codex command.

Use Inside tmux

Enable tmux mouse forwarding (You only need to configure this once; new tmux sessions will use it automatically.):

set -g mouse on

Start or attach a tmux session, enter your project, then run codex-tmux-scroll. Usage example:

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

All arguments are forwarded to the bundled Codex CLI, so normal Codex launch commands work:

codex-tmux-scroll resume
codex-tmux-scroll --dangerously-bypass-approvals-and-sandbox
codex-tmux-scroll --dangerously-bypass-approvals-and-sandbox resume

What It Does In tmux

  • Mouse wheel scrolls the Codex conversation instead of triggering prompt history navigation.
  • The scrolled history view is static: new output does not move the content you are reviewing.
  • A percentage indicator shows the current history position while scrolling.
  • The input prompt remains visible at the bottom while you review history.
  • Scrolling back to the bottom keeps the full history viewport plus the prompt.
  • Double-click the prompt area to jump back to the latest output.
  • Mouse drag selection works in the conversation history: select text with the left mouse button and release to copy it to the clipboard.
  • Existing local Codex auth, config, AGENTS.md, and project workflows continue to work.

Upstream Updates

This repository deliberately does not vendor the full Codex source tree. The tmux-specific changes are kept as a patch:

patches/codex-tmux-scroll-v0.139.0.patch

When Codex CLI releases a new version, this project is updated by rebasing that patch onto the new upstream tag, rebuilding the binary, and publishing a new GitHub release.

Build the current release locally:

CODEX_UPSTREAM_URL=<codex-cli-upstream-git-url> \
./scripts/build-from-source.sh

By default, the build script uses the patch file matching CODEX_UPSTREAM_REF. For example, rust-v0.139.0 uses:

patches/codex-tmux-scroll-v0.139.0.patch

The build uses the Rust toolchain selected by the upstream source tree. To force a specific toolchain, set CODEX_RUST_TOOLCHAIN.

Package a release archive:

CODEX_UPSTREAM_URL=<codex-cli-upstream-git-url> \
./scripts/package-release.sh

To update this project for a newer upstream Codex version:

  1. Choose the new upstream tag, for example rust-v0.140.0.
  2. First test whether the current patch still applies:
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
  1. If it builds and the tmux behavior still works, copy the patch forward:
cp patches/codex-tmux-scroll-v0.139.0.patch \
  patches/codex-tmux-scroll-v0.140.0.patch
  1. If the patch no longer applies, rebase it on the new upstream tag:
rm -rf worktrees/codex-rust-v0.140.0
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

Fix any rejected hunks, build and test the patched source, then save the new patch:

cd codex-rs
cargo build -p codex-cli --release
cd ..
git diff --binary -- . ':(exclude)codex-rs/Cargo.lock' > ../../patches/codex-tmux-scroll-v0.140.0.patch
  1. Package the new release:
CODEX_UPSTREAM_URL=<codex-cli-upstream-git-url> \
CODEX_UPSTREAM_REF=rust-v0.140.0 \
./scripts/package-release.sh

If you already built and tested a binary, package it without rebuilding:

CODEX_TMUX_SCROLL_BINARY_PATH=/path/to/target/release/codex \
./scripts/package-release.sh
  1. Publish a new GitHub release, for example v0.140.0-tmux.1, with:
dist/codex-tmux-scroll-x86_64-unknown-linux-gnu.tar.gz
dist/codex-tmux-scroll-x86_64-unknown-linux-gnu.tar.gz.sha256
install.sh

Users can update by rerunning the same installer command from the Install section; it downloads the latest release.

Release tags follow:

v<upstream-codex-version>-tmux.<patch-version>

Example:

v0.139.0-tmux.1
v0.140.0-tmux.1
v0.140.0-tmux.2

Status

  • Current base: Codex CLI 0.139.0
  • Current platform: Linux x86_64