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