Codex CLI With tmux: Keep a Remote Session Running

When you run Codex CLI over SSH on a remote machine, a dropped connection kills the terminal and ends the agent process. tmux, a terminal multiplexer, keeps the session running in the background so you can reconnect and find the work where you left it. The agent process keeps going even when no terminal is attached.

tmux solves the connection problem. It does not solve the progress problem. If the agent process ends before the task is done, you need to know where it stopped and what it had already completed. Keeping that record in a tool like fenbs means the next session picks up from a known point rather than from a guess.

What tmux does for a Codex CLI session

tmux creates a server process that hosts one or more named sessions. Each session has windows and panes, each of which runs a shell. You attach your terminal to a session to interact with it and detach when you want to leave. The session and everything running in it keeps going until the server process stops or the remote machine reboots.

For a long Codex CLI run, this means you can start the agent in a tmux session, close your laptop, and reopen it hours later to find the terminal exactly as you left it. You can also check on the session from a different machine by SSH-ing in and attaching.

Basic setup

On most Linux systems tmux is available from the package manager. On macOS, install it with Homebrew. Once installed, start a named session before launching Codex CLI:

tmux new-session -s codex
# inside the session:
codex "refactor the data pipeline"

To detach without stopping the session, press Ctrl-b d. The session keeps running. To list active sessions from outside:

tmux ls

To reattach to the session named codex:

tmux attach-session -t codex

What to do when the agent process ends

A session surviving does not guarantee the agent process inside it survived. Codex CLI might finish, error out, or hit a token limit. When you reattach and see a shell prompt instead of an active agent, the process has ended.

First check the terminal output above the prompt. It shows the last actions the agent took and whether it exited cleanly. Then check the repository state: run git diff and git status to see what changed during the run.

Use the output to decide whether to continue from where the agent stopped, revert a partial change, or review what was already completed before starting the next session. The Codex CLI best practices guide covers making checkpoints between distinct steps so recovery is straightforward.

Scrollback and logging

tmux keeps a scrollback buffer so you can read what happened before you reattached. The default buffer is limited. Increase it in ~/.tmux.conf to keep more history:

set-option -g history-limit 50000

For runs that span hours, pipe the agent output to a log file alongside the terminal. That log survives even if you lose the session entirely:

codex "refactor the data pipeline" 2>&1 | tee codex-run.log

Using multiple panes for parallel work

tmux supports multiple panes within one session window. A useful layout for a Codex CLI run is one pane running the agent and a second pane open to the repository so you can run git diff and check the current state without interrupting the agent. Create the second pane with Ctrl-b % for a vertical split or Ctrl-b " for a horizontal one.

If you are running multiple independent agent tasks at the same time, put each one in its own tmux window within the same session. Switch between windows with Ctrl-b n and Ctrl-b p. Each window has its own scrollback buffer and process group, so the outputs do not mix.

Limits of session-based persistence

tmux keeps the terminal session alive, not the AI context. When Codex CLI exits and you start a fresh run in the same session, the new instance has no memory of the previous one. The terminal history shows what ran, but the agent starts from scratch.

The session also ends if the remote machine reboots or the tmux server is killed. On shared servers this can happen without warning. Keep any progress record outside the session, in version control or in a project management tool, so it is available regardless of what happens to the machine.

How to do this with fenbs

1. Create a free account and add a task for the work you are running in the tmux session.
2. Before starting the Codex CLI run, check Where we left off in fenbs to confirm the starting state and any active rules.
3. After the run ends, add a comment to the task with what changed, what was verified, and what remains. Note the git commit hash if one was made.
4. If the session ended unexpectedly, record the last known state and the next step in Where we left off so any session can continue from there.
5. Connect Codex CLI to fenbs over MCP from Integrations so the agent can read the task context before starting and save progress before it exits.

For running Codex CLI on Windows where tmux is less common, see Codex CLI on Windows. For other harness options such as using a worktree to isolate changes, see Codex CLI worktree.