Brain· Mukutu

WezTerm

Recurso Em desenvolvimento

WezTerm / WezTerm

Terminal configurado na máquina da Ana (Windows): panes, abas, workspaces e seleção de texto sem mouse, tudo atrás de uma única tecla de comando (LEADER). Config em ~/.wezterm.lua (backup em ~/.wezterm.lua.bak), versão 20240203-110809-5046fc22. Artefato de origem: guia “WezTerm configurado” (30/07/2026).

O que e / What it is

Emulador de terminal com config versionável em Lua — recarrega ao salvar o arquivo, sem menu de preferências. Substitui o terminal padrão do Windows sem remover nada do que já funcionava no PowerShell. / A terminal whose whole configuration is a Lua file.

Quatro ganhos concretos:

  • Panes de verdade — vários shells lado a lado (servidor embaixo, editor em cima, logs ao lado).
  • Mão no teclado — copiar, buscar e navegar sem mouse; o copy mode usa teclas do Vim.
  • Workspaces por projeto — cada projeto guarda seu conjunto de abas/panes; troca de contexto em duas teclas.
  • Config versionável — dá para copiar entre máquinas e colocar no Git.

O LEADER / The leader key

Ctrl+q é a tecla de comando: aperta, solta, e então aperta a próxima tecla — igual ao tmux. Janela de 2 segundos para a segunda tecla. (Era Ctrl+a na config antiga.)

Panes: d divide na vertical · r divide na horizontal · h j k l navega · z zoom · x fecha · s entra em modo contínuo de redimensionar (TABLE: resize_pane no canto) · a modo de 1s para pular vários panes seguidos. Ctrl+Shift+[ abre o seletor visual (cada pane mostra uma letra).

Abas: c nova aba (ou Ctrl+Shift+T) · { } move a aba · Ctrl+Tab próxima (com Shift, anterior) · Alt+1..8 vai direto, Alt+9 na última · Ctrl+Shift+W fecha.

Workspaces: w lista · Shift+W cria · $ renomeia.

Copy mode: entra com [, sai com Esc/q/Ctrl+c. Fluxo: navegar (h j k l, w/b, 0 ^ $, g/G, Ctrl+f/Ctrl+b), v marca (V linha, Ctrl+v bloco), y copia e continua, Enter copia e sai. f<char>/t<char> pulam na linha; ; repete.

Busca: f busca no histórico da tela, ignorando maiúsculas.

Atalhos de fábrica que valem o hábito / Built-ins worth learning

  • Ctrl+Shift+Space — Quick Select. O melhor recurso escondido: etiqueta toda URL, caminho, hash de git, IP e número na tela; digita a etiqueta e vai pro clipboard. Etiqueta em maiúscula copia e já cola no shell. Ex.: rodou git log, quer o hash → duas teclas, sem mouse e sem copy mode.
  • Ctrl+Shift+P — command palette. Busca qualquer ação pelo nome (split, workspace, copy). É o escape para qualquer atalho esquecido.
  • Ctrl+Shift+L — debug overlay. Mostra os erros da config e abre um REPL Lua ao vivo. Primeiro lugar a olhar quando algo não funciona.
  • Ctrl+Shift+U insere caractere Unicode pelo nome. Ctrl+Shift+R força recarga da config. Alt+Enter tela cheia. Ctrl +/-/0 ajusta a fonte (padrão 11.0).

Shell integration (OSC 7 / OSC 133)

Pane novo abrindo no home em vez da pasta de trabalho é o padrão irritante do terminal. A correção não fica no .wezterm.lua — fica no profile do PowerShell (Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1), que passou a emitir duas sequências invisíveis junto do prompt:

  • OSC 7 informa o diretório atual → panes e abas novos herdam a pasta. Só dispara em caminho de filesystem real (dentro de Cert:\ ou HKLM:\ ele se omite).
  • OSC 133 marca onde cada prompt começa/termina → permite pular de comando em comando e selecionar a saída inteira de um comando.

Vale só para shells novos

Abas e panes já abertos continuam sem a integração — abra um novo para ver o efeito.

Além da janela / Beyond the window

  • Multiplexer. Panes e abas são a ponta visível de um mux server que roda separado da interface: a sessão sobrevive ao fechamento da janela e pode ser reanexada com tudo rodando — o que o tmux faz, sem instalar tmux. O mesmo mecanismo abre abas dentro do WSL ou de um host remoto por SSH na mesma janela (cada um é um domain).
  • wezterm cli monta o ambiente de trabalho por script:
wezterm cli split-pane --bottom --percent 30
wezterm cli spawn --cwd "C:/projetos/app" -- pwsh
wezterm cli send-text "npm run dev\n"
wezterm cli get-text          # captura o texto do pane atual
wezterm cli list              # janelas, abas e panes em tabela
  • Hyperlink rules — par regex → URL: o WezTerm varre o output e transforma cada acerto em link clicável. Duas ativas hoje: caminho de arquivo com linha abre no VS Code, e tarefa do Ekyte citada como #6773089 abre no Ekyte.
config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- caminho de arquivo com linha -> abre no VS Code
table.insert(config.hyperlink_rules, {
  regex = [==[\b([A-Za-z]:[\\/][^\s:()'"]+):(\d+)]==],
  format = 'vscode://file/$1:$2',
})

-- tarefa do Ekyte citada como #6773089
table.insert(config.hyperlink_rules, {
  regex = [==[\B#(\d{6,8})\b]==],
  format = 'https://app.ekyte.com/#/tasks/list/$1/edit',
})

Por que os colchetes levam

== [==[ … ]==] e a forma de colchete duplo simples são a mesma coisa em Lua: string literal longa, regex sem escape duplo. A config na máquina usa a forma simples; aqui vão os sinais de igual só para o trecho não ser confundido com wikilink do Obsidian por este vault e pelos verificadores de link.

Chamar default_hyperlink_rules() primeiro é obrigatório — atribuir a lista direto descarta a detecção de URL comum. O {6,8} na regra do Ekyte é proposital: sem ele, #1 e #42 virariam links quebrados. Caminho relativo com linha (src/Header.tsx:17) não é possível — exigiria o diretório atual, e format só interpola capturas $1–$9.

Como abrir o link: clique simples no shell normal; Shift+clique dentro de TUI (Claude Code, vim, tmux), porque a TUI liga mouse reporting e engole o clique; Ctrl+clique funciona nos dois casos. O Ctrl+clique veio de mouse_bindings e exige o par Down = Nop — sem ele o programa recebe “botão apertado” e nunca o “solto”, e passa a achar que você está arrastando.

Config quebrada não derruba o terminal — e é aí que engana

Campo inexistente faz o WezTerm rejeitar a config inteira, mostrar uma faixa de erro e seguir rodando a última config válida. A janela parece normal, mas com a config antiga: se um atalho novo não responde e há faixa de erro, é isso. Aconteceu aqui com show_close_tab_button_in_tabs, campo que não existe nesta versão. Cuidado extra com pipe: em cmd | head; echo $? o código de saída é do head, dá 0 mesmo com a config quebrada.

Validar sem aplicar e reverter:

out=$(wezterm --config-file "$HOME/.wezterm.lua" show-keys --lua 2>&1); code=$?
echo "EXIT=$code"; echo "$out" | grep -i "error\|not a valid" || echo "OK"
Copy-Item "$HOME\.wezterm.lua.bak" "$HOME\.wezterm.lua" -Force

Estado atual da config / Current state

Tema Tokyo Night com os 16 slots ANSI sobrescritos (todo slot ≥ 4.5:1 de contraste no fundo #1a1b26; slot 0 é #7e87ae, nunca preto), fonte JetBrainsMono Nerd Font 11.0, fundo opaco, 10.000 linhas de histórico, barra de abas sempre visível, aviso de atualização e bell sonoro ligados, sem barra de título nativa, shell powershell.exe -NoLogo. Sem Nerd Font instalada os triângulos das abas viram caixinhas — cosmético.

Por que importa para a Nova Mukutu / Why it matters

  • Ferramenta de base de quem opera IA no terminal: panes + wezterm cli deixam um agente rodando visível ao lado do trabalho, sem trocar de janela. Liga a Ferramentas na Pratica e Vibe-Coding Aplicado.
  • As hyperlink_rules fecham o ciclo terminal → Ekyte / VS Code: número de tarefa citado num log vira clique. Liga a Ekyte MCP.

Perguntas a responder / Questions to answer

  • Vale versionar o .wezterm.lua no mono para o time todo herdar a config?
  • Quais outras rotas merecem hyperlink_rules (issue do GitHub, card do kanban)?

Relacionado / Related

Fontes / Sources