codex-tmux-scroll

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

License

Apache-2.0. See LICENSE.

Third-party notices are kept in legal/THIRD_PARTY_NOTICES.md.