Guia do Desenvolvedor para tmux na Era da IA

tmux é um multiplexador de terminal: ele executa um processo de servidor persistente na sua máquina para que sessões, janelas e painéis sobrevivam a desconexões do terminal — você pode se desconectar de uma sessão, fechar o laptop, reconectar via SSH a partir de outra máquina e reanexar para encontrar cada processo exatamente onde estava. Essa única propriedade é a razão pela qual o tmux importa mais agora do que há uma década: os desenvolvedores executam cada vez mais processos de longa duração — servidores de desenvolvimento, watchers de build e agentes autônomos de codificação com IA como Claude Code e aider — que precisam sobreviver a uma conexão SSH instável ou a uma tampa fechada.

Este guia constrói o modelo mental primeiro (sessões, janelas, painéis, a tecla de prefixo), fornece uma configuração mínima que você pode colar uma vez e não precisar mais tocar, e então dedica tempo real à parte que nenhum outro guia de tmux aborda: usar o tmux como host durável para agentes de codificação com IA. Ele termina com uma comparação honesta de quando usar o tmux e quando um terminal moderno como Zellij ou Warp é a ferramenta mais adequada.

O Que é o tmux e o Problema que Ele Resolve

O tmux é um multiplexador de terminal que permite que uma janela de terminal hospede muitas sessões, janelas e painéis persistentes. O mecanismo por trás de sua persistência é uma arquitetura cliente-servidor: quando você executa tmux, ele inicia um processo de servidor de longa duração que gerencia suas sessões, e seu terminal se conecta a esse servidor como cliente. Quando sua conexão SSH cai, sua sessão tmux não cai — porque o processo do servidor é executado independentemente de qualquer conexão de cliente. Seu terminal é apenas uma visualização; a sessão continua em execução, esteja você conectado ou não.

O tmux resolve dois problemas ao mesmo tempo. O primeiro é a persistência: um build que leva 40 minutos, um servidor de desenvolvimento ou um agente de IA no meio de uma tarefa continuam em execução após a morte da sua sessão ssh. Você reconecta e reanexe. O segundo é o layout: em vez de gerenciar abas de terminal, você divide uma janela em painéis — editor à esquerda, log do servidor à direita, um shell na parte inferior — todos visíveis ao mesmo tempo e todos reproduzíveis.

O tmux foi criado em 2007 por Nicholas Marriott como uma alternativa licenciada sob ISC ao GNU screen. Os exemplos neste guia usam o tmux 3.6b. Instale-o com seu gerenciador de pacotes:

# macOS
brew install tmux

# Debian / Ubuntu / WSL
sudo apt install tmux

# Fedora / RHEL
sudo dnf install tmux

tmux -V   # confirmar a versão

A Hierarquia de Sessões, Janelas e Painéis

O tmux organiza o trabalho em três camadas: uma sessão é um espaço de trabalho nomeado e persistente (um por projeto); janelas são abas dentro dessa sessão; painéis são divisões dentro de uma janela. A tecla de prefixo — padrão Ctrl+b, convencionalmente remapeada para Ctrl+a — controla todos os comandos do tmux. Você pressiona o prefixo, solta e então pressiona a tecla de comando.

A analogia mais clara mapeia para um editor que você já conhece: uma sessão é como uma janela inteira do editor para um projeto, as janelas são as abas dentro dela e os painéis são as visualizações divididas dentro de uma aba. Você pode ter uma sessão frontend e uma sessão backend; dentro de backend, uma janela para a aplicação e outra para o banco de dados; dentro da janela da aplicação, um painel executando o servidor e outro para comandos ad-hoc.

Como o prefixo controla os comandos, cada atalho de teclado abaixo pressupõe que você pressiona o prefixo primeiro. O prefixo padrão é Ctrl+b; a configuração na próxima seção o remapeia para Ctrl+a, que é mais fácil de alcançar.

O Conjunto Essencial de Comandos

Esses comandos cobrem 90% do uso diário do tmux: criar e nomear sessões, desconectar e reanexar, dividir e navegar entre painéis e rolar pelo histórico de saída. Você executa comandos de nível de sessão a partir do seu shell; comandos de painel e janela são executados dentro do tmux via prefixo.

Gerenciamento de sessões a partir do shell:

tmux new -s project       # criar uma sessão nomeada
tmux ls                   # listar sessões em execução
tmux attach -t project    # reanexar a uma sessão
tmux kill-session -t project

Dentro de uma sessão, com o prefixo (mostrado aqui como o Ctrl+a remapeado):

• prefix d — desconectar; a sessão continua em execução em segundo plano.
• prefix c — criar uma nova janela.
• prefix n / prefix p — próxima / janela anterior.
• prefix % — dividir o painel atual verticalmente (esquerda/direita).
• prefix " — dividir horizontalmente (superior/inferior).
• prefix + teclas de seta — mover entre painéis.
• prefix z — ampliar o painel atual para tela cheia; pressione novamente para restaurar.
• prefix [ — entrar no modo de cópia para rolar e pesquisar; no modo vi, / pesquisa, n/N pula entre correspondências, q sai.

O ciclo de desconexão/reanexação é o fluxo de trabalho central: desconecte com prefix d, mude para outra máquina, reanexe com tmux attach -t nome-do-projeto e retome exatamente de onde parou. Para uma referência completa de atalhos de teclado, mantenha um tmux cheat sheet à mão — memorizar a página de manual inteira é desnecessário.

Um ~/.tmux.conf Mínimo que Você Pode Colar Uma Vez

Uma configuração mínima de tmux precisa exatamente de quatro coisas: uma tecla de prefixo remapeada (Ctrl+a é mais ergonômico que Ctrl+b), suporte a mouse (set -g mouse on), modo de cópia vi e atalhos intuitivos de divisão — todo o resto é cosmético e pode esperar. Aqui está essa configuração, com um comentário em cada linha explicando por que ela existe. Cole-a em ~/.tmux.conf e recarregue com tmux source-file ~/.tmux.conf.

# --- prefixo ------------------------------------------------
unbind C-b                 # remover o prefixo padrão
set -g prefix C-a          # Ctrl+a está mais próximo da posição de repouso
bind C-a send-prefix       # pressione Ctrl+a duas vezes para enviar um Ctrl+a literal

# --- usabilidade --------------------------------------------
set -g mouse on            # clicar em painéis, arrastar bordas, rolar nativamente
set -g history-limit 10000 # manter mais histórico de rolagem que o padrão de 2000
set -g base-index 1        # numerar janelas a partir de 1, não 0
setw -g pane-base-index 1  # numerar painéis a partir de 1 também

# --- modo de cópia ------------------------------------------
setw -g mode-keys vi       # teclas vi no modo de cópia
bind v copy-mode           # prefix v para entrar no modo de cópia rapidamente

# --- divisões mais intuitivas --------------------------------
bind | split-window -h -c "#{pane_current_path}"  # | divide esquerda/direita
bind - split-window -v -c "#{pane_current_path}"  # - divide superior/inferior
# ambas abrem no diretório do painel atual

# --- recarregar ---------------------------------------------
bind r source-file ~/.tmux.conf \; display "recarregado"

Algumas notas sobre sintaxe e versões. set -g mouse on é a forma correta de opção única para o tmux 2.1 e versões posteriores; o tmux 2.1 (2015) consolidou as quatro opções antigas (mode-mouse, mouse-select-pane, mouse-resize-pane, mouse-select-window) em uma. Se você encontrar uma configuração antiga usando mode-mouse on, é por isso que ela parece diferente. O flag -c "#{pane_current_path}" faz com que novas divisões herdem o diretório atual — um detalhe pequeno que você vai sentir falta imediatamente se estiver ausente.

Essa é a configuração completa. Resista à tentação de adicionar um tema para a barra de status no primeiro dia. Se você quiser um mais tarde, o plugin Catppuccin para tmux (tag atual v2.3.0) requer tmux 3.2+, e seu README recomenda um clone manual em vez do gerenciador de plugins por causa de um conflito de nome.

Fluxos de Trabalho Modernos: tmux como Host para Agentes de Codificação com IA

O tmux é o host natural para agentes de codificação com IA de longa duração. Desconecte uma sessão do Claude Code ou do aider antes de fechar o laptop, reanexe de qualquer máquina com tmux attach -t agent e o processo do agente — com todo o seu histórico de saída — estará esperando por você. Tanto o Claude Code quanto o aider são CLIs de terminal, então isso não é uma integração especial: é o comportamento padrão de qualquer processo em primeiro plano sendo executado em uma sessão tmux, aplicado a uma ferramenta que pode rodar por muitos minutos sem supervisão.

Sessões de codificação agêntica são exatamente o tipo de carga de trabalho que o tmux foi criado para proteger. Um agente refatorando uma grande base de código ou executando um longo ciclo de testes é um processo que você não quer vinculado ao tempo de vida da sua conexão SSH. Inicie-o dentro do tmux e ele sobrevive à queda.

Acompanhe um Agente Enquanto Trabalha

O layout mais útil é um agente em um painel e um editor em outro, lado a lado. Inicie uma sessão, divida-a e execute o agente em um lado:

tmux new -s agent
# dentro da sessão:
#   prefix |   -> dividir esquerda/direita
#   painel esquerdo:  claude   (ou: aider)
#   painel direito:   nvim .

Você acompanha o raciocínio e os diffs do agente à esquerda enquanto revisa ou edita à direita, tudo em uma janela, tudo sobrevivendo a desconexões.

Supervise Múltiplos Agentes com Painéis Sincronizados

Quando você executa vários agentes em paralelo — digamos, a mesma tarefa em branches diferentes — painéis sincronizados permitem que você os controle juntos. Com setw -g synchronize-panes on, cada tecla que você digita é enviada a todos os painéis da janela simultaneamente, o que é útil para emitir o mesmo prompt em múltiplas sessões de agentes ou redefinir um conjunto de processos paralelos de uma vez. Desative-o da mesma forma (synchronize-panes off) quando quiser interagir com um painel individualmente. Um modo de falha comum que encontramos com painéis sincronizados é esquecer que a sincronização está ativa e transmitir um comando destrutivo para todos os painéis — vincule-o a uma tecla com um indicador visível para que seu estado nunca seja ambíguo.

Um Layout de Agente via Script

Para obter um layout de supervisão reproduzível com três painéis — agente à esquerda, editor no canto superior direito, logs no canto inferior direito — sem nenhuma dependência extra, salve este script em ~/bin/tmux-agent.sh:

#!/usr/bin/env bash
set -euo pipefail
SESSION="agent"

# Primeiro painel: o agente (esquerda). -d cria a sessão desanexada.
tmux new-session -d -s "$SESSION" -x "$(tput cols)" -y "$(tput lines)"
tmux send-keys -t "$SESSION" "claude" C-m          # agente, esquerda

# Dividir o lado direito para o editor; o novo painel torna-se ativo.
tmux split-window -h -t "$SESSION"
tmux send-keys -t "$SESSION" "nvim ." C-m          # editor, superior direito

# Dividir o painel direito para logs; o novo painel torna-se ativo.
tmux split-window -v -t "$SESSION"
tmux send-keys -t "$SESSION" "tail -f dev.log" C-m # logs, inferior direito

# Focar o painel do agente e anexar. Usar direção (-L) em vez de
# índices de painel fixos mantém isso correto independentemente do base-index.
tmux select-pane -t "$SESSION" -L
tmux attach -t "$SESSION"

Execute chmod +x ~/bin/tmux-agent.sh uma vez e então tmux-agent.sh sempre que iniciar o trabalho. O agente continua em execução se você se desconectar; reanexe de qualquer lugar.

Persistência e Plugins

As sessões do tmux sobrevivem a desconexões, mas não sobrevivem a uma reinicialização por conta própria — para isso, você precisa de plugins que serializam e restauram o estado. A pilha padrão é o Tmux Plugin Manager (TPM) mais o tmux-resurrect e o tmux-continuum. Instale o TPM com:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Em seguida, adicione as linhas de plugin ao final de ~/.tmux.conf e pressione prefix + I para instalar:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
run '~/.tmux/plugins/tpm/tpm'   # mantenha esta linha por último

Entenda o que cada plugin realmente faz. O tmux-resurrect salva e restaura o layout da sua sessão — janelas, painéis e diretórios de trabalho — automaticamente. A restauração dos programas que estavam em execução é opcional e limitada a uma lista de permissões configurada (@resurrect-processes), com sessões de editor tratadas por @resurrect-strategy-vim/nvim e o conteúdo do texto do painel preservado apenas quando @resurrect-capture-pane-contents 'on' está definido. Não presuma que seu agente se reiniciará na restauração; ele não vai, a menos que você o tenha adicionado à lista de permissões.

O tmux-continuum automatiza o salvamento a cada 15 minutos por padrão (configurável via @continuum-save-interval) e restaura na inicialização do servidor tmux somente quando @continuum-restore 'on' está habilitado. Juntos, eles significam que uma reinicialização custa apenas um recarregamento de layout, não uma reconstrução do zero.

Layouts Declarativos com tmuxp

Para layouts que você inicializa repetidamente, defina-os uma vez em YAML com o tmuxp (repositório: tmux-python/tmuxp) ou o Tmuxinator baseado em Ruby. O tmuxp lê configurações do diretório XDG ~/.config/tmuxp/ (o caminho legado ~/.tmuxp/ ainda funciona). Aqui está o layout de supervisão de agente como ~/.config/tmuxp/agent.yaml:

session_name: agent
windows:
  - window_name: supervise
    layout: main-vertical
    shell_command_before:
      - cd ~/code/project
    panes:
      - claude
      - nvim .
      - tail -f dev.log

Carregue-o com tmuxp load agent. As chaves aqui — session_name, windows, window_name, layout, shell_command_before, panes — são todas atuais no tmuxp 1.70.x. Este é o equivalente declarativo do script bash acima: um comando, o mesmo layout reproduzível toda vez.

Quando NÃO Usar o tmux

Se você trabalha localmente e não acessa máquinas remotas via SSH ou executa processos em segundo plano de longa duração, um terminal moderno como Zellij ou Warp oferece multiplexação com melhores padrões e sem a curva de aprendizado da tecla de prefixo; a vantagem do tmux é especificamente sua persistência do lado do servidor e capacidade de script via SSH. Recorrer ao tmux quando as abas nativas do seu terminal seriam suficientes é adicionar complexidade sem nenhum ganho.

Algumas notas decisivas. O Zellij é um multiplexador baseado em Rust com um sistema baseado em modos em vez de uma única tecla de prefixo, persistência e serialização de sessão integradas e um preset opcional no estilo tmux; está em desenvolvimento ativo e ainda é pré-1.0. O Warp é um terminal multiplataforma — macOS, Linux e Windows — com sugestões de comandos integradas por IA, e seu cliente foi disponibilizado como código aberto (MIT + AGPL v3) em abril de 2026, tornando-o uma opção viável no Linux, não apenas uma ferramenta exclusiva para macOS. Use o tmux quando você acessa máquinas remotas via SSH, executa processos de longa duração (watchers de build, servidores de desenvolvimento, agentes de IA) ou precisa de layouts reproduzíveis via script. Use um terminal moderno quando quiser esses recursos com menos cerimônia e não precisar da profundidade de script ou da amplitude de plugins do tmux.

Conclusão

A razão pela qual o tmux merece um lugar em um fluxo de trabalho orientado a agentes é a mesma razão pela qual ele conquistou seu espaço via SSH anos atrás: ele desacopla um processo em execução do terminal que o observa. Inicie sua próxima execução longa de agente dentro de tmux new -s agent, desconecte quando se afastar e reanexe de onde estiver — o trabalho continua sem você. Cole a configuração mínima acima, adicione o tmux-resurrect quando as reinicializações começarem a custar seus layouts e crie o script do layout do agente uma vez para nunca precisar reconstruí-lo manualmente.

Perguntas Frequentes

O que acontece com um processo em execução no tmux quando o servidor tmux é encerrado ou a máquina reinicia?

O processo é encerrado. A persistência do tmux protege apenas contra desconexões de clientes, não contra o encerramento do servidor, portanto, encerrar o servidor com tmux kill-server ou reiniciar a máquina termina todos os processos em execução e descarta todas as sessões. Para sobreviver a uma reinicialização, você precisa do tmux-resurrect para salvar o layout e do tmux-continuum para restaurá-lo na inicialização do servidor, mas mesmo assim o layout é restaurado, não os programas em execução, a menos que você adicione processos específicos à lista de permissões via a opção resurrect-processes.

Qual é a diferença entre janelas e painéis no tmux?

Uma janela é uma aba em tela cheia dentro de uma sessão, e um painel é uma região dividida dentro de uma única janela. Alternar entre janelas substitui a tela inteira por uma aba diferente usando prefix n ou prefix p, enquanto os painéis dividem uma janela visível em regiões lado a lado ou empilhadas pelas quais você navega com prefix e as teclas de seta. Use janelas para separar tarefas distintas, como uma aplicação e seu banco de dados, e painéis para visualizar processos relacionados ao mesmo tempo, como um editor ao lado de um log em tempo real.

Preciso remapear a tecla de prefixo de Ctrl+b para Ctrl+a?

Não, o remapeamento é opcional e é puramente uma escolha ergonômica. O prefixo padrão Ctrl+b funciona para todos os comandos do tmux sem nenhuma configuração. Muitos usuários o remapeiam para Ctrl+a porque as teclas ficam mais próximas no teclado, mas isso conflita com o mesmo atalho no GNU screen e com o atalho do readline que move o cursor para o início de uma linha. Se você remapear para Ctrl+a, adicione bind C-a send-prefix para que pressioná-lo duas vezes ainda envie um Ctrl+a literal para o shell.

Devo usar tmux ou Zellij para executar agentes de codificação via SSH?

Ambos funcionam porque cada um executa um servidor no host remoto que mantém as sessões ativas entre desconexões, então a escolha se resume a padrões e ecossistema. Escolha o tmux quando quiser um ecossistema de plugins grande e maduro, alta capacidade de script via bash ou tmuxp e atalhos que já estão instalados na maioria dos servidores. Escolha o Zellij quando preferir controles baseados em modos e intuitivos em vez de um modelo de tecla de prefixo e quiser serialização de sessão sem configurar plugins. O Zellij ainda é pré-1.0, portanto o tmux é a escolha mais conservadora para configurações de longa duração.