tmux-remote-linux

Some projects cannot be tested from a developer laptop. The code is local, but the meaningful validation happens behind bastion hosts, MFA, jump scripts, private kubeconfigs, internal datasets, or Kubernetes clusters.

tmux-remote-linux closes that loop through a tmux pane you already control. You log in and prepare the shell yourself; Codex, Claude Code, Gemini CLI, or another AI coding agent only reads and writes that pane.

This skill is designed for reliable shell operations, not full terminal interactivity. Do not hand the pane to an agent while it is inside a REPL or full-screen TUI such as MySQL, Redis, Python, Node, Spark shell, vim, less, or top. Even an apparent exit from a non-shell CLI is not handled here; that belongs to the dedicated skill for that CLI.

For the full manual, configuration reference, and troubleshooting notes, see docs/reference.en.md. A Chinese version is available at docs/reference.zh-CN.md. For building other tmux-* interactive-environment skills, see docs/tmux交互式环境skill开发规范.md.

Platform Notes

macOS and Linux are the primary supported environments. On Windows, use WSL and install Codex, Claude Code, Gemini CLI, tmux, and this skill inside the same WSL distribution.

Quick Start

If tmux is not installed yet, install it with your normal package manager first, for example brew install tmux, sudo apt-get install tmux, sudo yum install tmux, or sudo dnf install tmux.

Create a local tmux session named remote:

tmux new -s remote

Inside that tmux window, log in to the remote machine yourself:

ssh your-bastion-or-host
ssh your-target-host

Leave that tmux pane open. By default, this skill operates remote:0.0.

Install For Your AI Tool

Codex

Copy this skill into Codex's skills directory:

mkdir -p "$HOME/.codex/skills/tmux-remote-linux"
cp SKILL.md "$HOME/.codex/skills/tmux-remote-linux/"
cp -R scripts "$HOME/.codex/skills/tmux-remote-linux/"
chmod +x "$HOME/.codex/skills/tmux-remote-linux/scripts/"*.sh

Then ask Codex something like:

使用 tmux-remote-linux。目标是 remote:0.0，环境是 non-production。请先读取当前 pane。

For future tasks, tell the agent to use this skill instead of direct ssh. Even if a normal SSH connection would work, prepare the tmux pane yourself and let the agent operate that pane.

Claude Code

Create a command that points Claude Code to this skill:

mkdir -p "$HOME/.claude/commands"
cat > "$HOME/.claude/commands/tmux-remote.md" << 'EOF'
Read and follow /path/to/tmux-remote-linux/SKILL.md, then execute the bundled scripts there.
EOF

Replace /path/to/tmux-remote-linux with this repository's path. Then use /tmux-remote in Claude Code.

Gemini CLI

Create a command that points Gemini CLI to this skill:

mkdir -p "$HOME/.gemini/commands"
cat > "$HOME/.gemini/commands/tmux-remote.toml" << 'EOF'
description = "Read and write a remote Linux terminal through tmux"

prompt = """
Read and follow /path/to/tmux-remote-linux/SKILL.md, then execute the bundled scripts there.
"""
EOF

Replace /path/to/tmux-remote-linux with this repository's path. Then use /tmux-remote in Gemini CLI.

Daily Use

Most users only need to remember three things:

• Default target: remote:0.0
• You must choose an environment: production or non-production
• Short checks use run.sh; cd, export, and long-running shell commands use send.sh; both are shell-only. REPL-style CLIs are not supported by this skill.
• Pass the whole shell command as one quoted argument, for example scripts/run.sh 'pwd; hostname'.
• For long, script-like, or heavily quoted logic, do not ask the agent to build a huge one-liner. The preferred workflow is: generate a local temporary script, usually .sh or .py, optionally syntax-check it locally, base64 it through run.sh/send.sh into a unique remote /tmp path, execute it with the matching interpreter such as bash or python3, preserve the exit code, and clean it up.
• Commands sent by run.sh and send.sh are logged locally as JSONL under ~/.codex/tmux-remote-linux/logs by default; run.sh records output and exit code, while send.sh records only that input was sent.
• Use scripts/logs.sh last, scripts/logs.sh failures, scripts/logs.sh grep <pattern>, or scripts/logs.sh show <request_id> to query local logs.

If the pane is inside a non-shell CLI such as mysql>, python>>>, spark-sql>, or an internal tool prompt, use a dedicated skill for that CLI. The dedicated skill should know how to enter and leave its own prompt and should send raw CLI syntax, not shell-wrapped commands.

Do not send concurrent input to the same tmux target. A tmux pane is a serial interactive channel. Wait for one command or recovery action to finish before starting another command on that same pane.

Treat the target tmux pane as agent-managed. Avoid typing your own commands into the same pane while the AI is using it. If you need manual work, open another terminal, pane, or session, or ask the agent to run the command. If you did change the managed pane manually, tell the agent what changed before asking it to continue.

Best practice: detach the managed tmux session. After the remote shell is ready, detach with Ctrl-b d and let the agent operate it in the background. Re-attach with tmux attach -t remote only when you need to type a secret or intentionally take over, then detach again.

Sensitive prompts are user-owned. Do not paste passwords, MFA codes, tokens, private keys, or other secrets into the AI chat. If a command asks for a secret, type it directly in the tmux pane, then tell the agent that the step is complete.

Useful tmux commands:

tmux ls                     # list sessions
tmux new -s remote          # create and enter a session
tmux attach -t remote       # re-enter a session
tmux list-panes -a          # find pane targets
tmux kill-session -t remote # close the remote session

If your pane is not remote:0.0, tell the AI the correct target, for example remote:0.1.

Production Use

In production, every command must be approved by you before it is sent to tmux. The AI should show the target, environment, exact command, and a one-digit approval challenge. Only reply with that digit if you understand and approve that exact command.

Do not allow an AI tool to set production approval environment variables by itself. They are only a relay of your explicit approval.

Token Usage

Using a remote tmux pane can use slightly more tokens than local coding because the AI needs to read terminal context and summarize remote output. For normal use, you usually do not need to tune anything.

If output gets large, ask the AI to read fewer pane lines, use tail -n, narrow logs with grep, or reduce these settings:

REMOTE_TMUX_LINES=20
REMOTE_TMUX_RUN_MAX_OUTPUT_LINES=80
REMOTE_TMUX_RUN_PENDING_OUTPUT_LINES=20
REMOTE_TMUX_LOG_MAX_OUTPUT_LINES=10

See docs/reference.en.md for all settings and edge cases.