tmux-remote-linux
lenovobenben/tmux-remote-linux
Agentes IA operando servidores remotos via tmux pré-autenticado
Ver no GitHubAgent para operar ambientes Linux remotos através de um painel tmux, mesmo atrás de bastion hosts, jump servers, MFA e redes privadas. Permite que agentes de IA (Claude, Codex, Gemini) leiam e escrevam em um terminal remoto já autenticado, sem precisar gerenciar credenciais ou túneis SSH diretos.
Instalação
npx convez-ai lenovobenben/tmux-remote-linux1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Validar código em ambientes protegidos por bastion hosts
- Executar testes e deployments em infraestrutura interna
- Automatizar tarefas em servidores Kubernetes privados
Veredito

Ferramenta especializada e bem arquitetada para um caso de uso específico: dar aos agentes IA acesso seguro a ambientes remotos protegidos. Requer configuração manual mas oferece isolamento robusto e evita exposição de credenciais. Essencial para times que operam infraestrutura privada.
README
A tradução para o português deste README ainda está na fila.
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:
productionornon-production - Short checks use
run.sh;cd,export, and long-running shell commands usesend.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'. - Commands sent by
run.shandsend.share logged locally as JSONL under~/.codex/tmux-remote-linux/logsby default;run.shrecords output and exit code, whilesend.shrecords only that input was sent. - Use
scripts/logs.sh last,scripts/logs.sh failures,scripts/logs.sh grep <pattern>, orscripts/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.