Configuração

A maioria dos ajustes persistentes fica em um único arquivo:

~/.config/zshell/config.toml

A janela Ajustes (Cmd+,) grava esse mesmo arquivo. Algumas preferências do macOS — idioma e atualizações automáticas — ficam em outro lugar e são listadas no final desta página.

Novas configurações ativam as dicas de comandos Vim, a restauração do histórico de sessões e as notificações de comandos com falha. O download automático de atualizações também vem ativado. As configurações existentes e as escolhas salvas são preservadas.

Como o arquivo funcionaCopiar link

Antes de editar manualmente, considere:

• Mudanças são lidas durante a execução. Edições externas válidas se aplicam automaticamente; ajustes para novos terminais ainda exigem um novo painel. Arquivos ilegíveis ou malformados mantêm os últimos ajustes válidos. Um arquivo intencionalmente vazio restaura os padrões após uma breve espera.
• O Zshell reescreve o arquivo quando muda um ajuste armazenado nele. O arquivo é regenerado, então comentários e chaves desconhecidas se perdem na próxima utilização desses controles. Escolha uma forma principal de edição ou mantenha uma cópia oficial nos seus dotfiles.
• A maioria dos valores padrão é omitida. font-size, terminal.vim-command-hints, terminal.restore-history, terminal.notify-on-error são sempre gravados. Remover uma dessas três chaves de terminal em um arquivo existente desativa o recurso; remover outras chaves restaura os valores padrão.
• O parser é propositalmente pequeno. Suporta chaves simples, chaves com pontos, cabeçalhos [table], comentários # e valores de texto, número e booleano. Não suporta arrays, tabelas em linha ou strings com múltiplas linhas.
• Valores inválidos usam um fallback seguro. Tamanhos fora da faixa, backends desconhecidos e nomes de temas incorretos não impedem o aplicativo de abrir.

Ao salvar, os links simbólicos de arquivos e diretórios são mantidos; o destino é atualizado atomicamente preservando as permissões. Edições externas não reescrevem comentários nem chaves desconhecidas; salvar depois em Ajustes ainda regenera o arquivo como descrito acima.

Presença do aplicativoCopiar link

app-presenceCopiar link

"dock" · "dock-and-menu-bar" · "menu-bar" — padrão "dock"

Escolha Ajustes → Geral → Mostrar Zshell em para mudar imediatamente. "dock" exibe apenas o ícone do Dock, "dock-and-menu-bar" exibe ambos e "menu-bar" exibe apenas o ícone da barra de menus.

A barra de menus abre o espaço de trabalho atual, o terminal rápido, os ajustes e a busca de atualizações. Nos dois modos com barra de menus, fechar a última janela a oculta e mantém seus terminais e tarefas em execução. Abrir espaço de trabalho retorna à mesma janela, projeto e sessão. Fechar outra janela, painel ou projeto continua encerrando suas tarefas. Sair segue terminal.preserve-sessions; Sair e encerrar todas as sessões encerra todas. O modo é mantido após reiniciar.

AparênciaCopiar link

themeCopiar link

"system" · "light" · "dark" — padrão "system"

Escolhe a aparência do aplicativo. "system" segue o macOS; os outros dois fixam uma aparência.

theme-dark e theme-lightCopiar link

Texto — padrões "Default Dark" e "Default Light"

Tema de cores de cada aparência. Um tema recolore terminais, moldura da janela, barras laterais, editor e diffs em conjunto. Os padrões mantêm a barra lateral translúcida; outros temas a pintam de acordo com sua paleta.

Os Ajustes mostram o catálogo selecionado de temas compartilhado pelos dois backends. Um nome escrito manualmente deve corresponder exatamente ao nome exibido, incluindo maiúsculas e minúsculas; caso contrário, usa-se o padrão correspondente.

toolbar.visibilityCopiar link

"hide" · "auto" · "always" — padrão "hide"

Controla a barra compacta abaixo da aba ativa:

• "hide" a mantém oculta.
• "auto" só mostra quando o diretório do projeto é um repositório Git.
• "always" mantém o acesso ao Git em todos os projetos, incluindo Sem Repositório Git.

Consulte A barra de ferramentas Git para ver seu conteúdo.

TextoCopiar link

font-familyCopiar link

Texto — padrão "", indicando JetBrains Mono incluída

Terminal, editor e visualizador de diffs compartilham essa família latina. Use nome de família, não de estilo: "IBM Plex Mono", não "IBM Plex Mono Regular". Famílias desconhecidas ou não monoespaçadas usam a fonte incluída.

A ordem de fallback no terminal é família latina, família CJK opcional abaixo, Symbols Nerd Font incluída e fallback do sistema do backend. Editor e diffs mantêm seus fallbacks normais de macOS/WebKit.

terminal.font-fallback-familyCopiar link

Texto — padrão "", indicando fallback do backend/sistema

Acrescenta uma família CJK instalada à cadeia de fallback do terminal. O seletor inclui famílias com glifos representativos de chinês, japonês ou coreano; não exige que sejam estritamente monoespaçadas porque só fornecem glifos ausentes na fonte latina principal.

font-sizeCopiar link

Número, 8–32 — padrão 13

Tamanho compartilhado do texto de terminal, editor e diffs, em pontos. É a única chave gravada mesmo quando tem o valor padrão.

interface.scaleCopiar link

Número, 0.9–1.5 — padrão 1

Escala abas, ícones, botões, barras laterais e o restante da interface. O conteúdo de terminal, editor e diffs mantém o tamanho de fonte configurado separadamente acima.

sidebar.font-sizeCopiar link

Número, 9–24 — padrão 14

Tamanho base do texto das duas barras laterais. Títulos de seções, linhas, metadados e controles mantêm a hierarquia relativa quando a base muda.

terminal.font-thickenCopiar link

Booleano — padrão false

Renderiza os glifos com traços levemente mais grossos, semelhante à suavização clássica do macOS. Ambos os backends respeitam a opção, e a prévia dos Ajustes mostra o resultado. Configurações antigas font-thicken ainda são lidas e depois regravadas com a chave atual com pontos.

terminal.font-thicken-strengthCopiar link

Inteiro, 0–255 — padrão 255

Controla a intensidade quando terminal.font-thicken é true. Zero é o engrossamento mais leve disponível, não desativado. Ghostty usa a intensidade nativa do macOS; Alacritty mapeia a mesma faixa para um traço CoreText. A direção e os extremos coincidem, mas os pixels rasterizados podem diferir.

terminal.line-heightCopiar link

Número, 0.75–2 — padrão 1

Multiplica a altura natural da célula de cada backend, mantendo os glifos centralizados verticalmente. Altera apenas as linhas do terminal, não o espaçamento de editor e diffs.

O Zshell não expõe um controle de peso base da fonte. Ghostty escolhe estilos nomeados ou eixos variáveis; Alacritty/CoreText resolve as faces regular e negrito por atributos. Um valor compartilhado não manteria consistentemente a distinção regular/negrito e os pesos de fallback entre fontes estáticas e variáveis.

editor.wrap-linesCopiar link

Booleano — padrão true

Quebra visualmente linhas longas na largura do painel do editor de arquivos. Em false, elas rolam horizontalmente. Não altera a quebra de linhas do terminal nem dos diffs.

TerminalCopiar link

terminal.startup-program / terminal.startup-argumentsCopiar link

Textos — não definidos por padrão

Escolhem o executável e vetor de argumentos para terminais criados depois da alteração. Sem terminal.startup-program, o Zshell continua usando o shell de login da conta com -l. O programa deve ser um caminho absoluto executável; um caminho ausente ou não executável volta ao shell de login em vez de abrir um painel inoperante.

terminal.startup-arguments é dividido em argumentos sem invocar um shell. Aspas e barras invertidas preservam os limites, inclusive espaços e argumentos vazios, mas variáveis, globs e substituições de comandos não são expandidos. Aspas inválidas também retornam ao shell de login. Um argv explícito fornecido pelo CLI Zshell ainda tem prioridade naquele terminal.

terminal.backendCopiar link

"libghostty" · "alacritty" — padrão "libghostty"

Escolhe o emulador de terminais novos. Painéis existentes mantêm o backend inicial. Ambos são nativos, acelerados por GPU, suportam imagens e usam os mesmos temas; Alacritty geralmente consome menos memória.

Veja Backends de terminal para as variáveis de ambiente e o contrato de compatibilidade.

terminal.macos-option-as-altCopiar link

Booleano — padrão false

Em true, combinações com Option vão aos programas como atalhos Alt/Meta. O padrão deixa Option com a fonte de entrada ativa do macOS para que layouts como Polish Pro possam digitar caracteres compostos.

terminal.bellCopiar link

Booleano — padrão true

Controla o som e a solicitação visual de atenção do macOS quando um programa toca o sinal. Em false, não há som, notificação de sinal do terminal nem pedido de atenção no Dock. Tecnologias assistivas ainda recebem o sinal como anúncio semântico. Ambos os backends respeitam a opção.

terminal.vim-command-hintsCopiar link

Booleano — padrão true

Mostra comandos Vim / Neovim conforme o modo abaixo das informações da sessão em Info. Aplica imediatamente nos dois backends, incluindo editores reconhecíveis por SSH. Veja Dicas de comandos Vim para os requisitos de detecção.

terminal.restore-historyCopiar link

Booleano — padrão true

Restaura a saída anterior acima de um shell novo após reiniciar. O conteúdo é texto estático, não um processo sobrevivente.

A saída restaurada fica no disco, portanto pode incluir segredos exibidos no terminal. Projetos, abas e layout são restaurados independentemente dela.

AutomaçãoCopiar link

ai.enabledCopiar link

Booleano — padrão true

Permite que agentes compatíveis coordenem painéis de fundo quando você pede em linguagem natural e mostra o estado de ciclo de vida informado pelo provedor. O Zshell não deduz estado pelo texto do terminal. Recomenda-se usar o controle dos Ajustes: erros são mostrados junto dele e configurações existentes conflitantes não são alteradas.

O fluxo de uso está em Trabalhar com agentes de IA.

Ao compartilhar o app-server do Codex, Zshell associa IDs de conversa verificados ao painel em primeiro plano. Correspondências ambíguas ficam sem vínculo. A integração gerenciada adiciona session-id ao título do Codex e preserva os demais itens.

ai.resume-conversationsCopiar link

booleano — padrão true

Ao restaurar os painéis de terminal, retoma exatamente a conversa original registrada de Claude Code, Codex, Pi ou OpenCode quando o PTY original está indisponível. Requer ai.enabled = true. Sem uma conversa verificada, o painel abre um novo shell; o Zshell nunca escolhe a conversa mais recente pelo diretório.

Controle em Ajustes → Automação → Retomar conversas de agentes. Esta opção é independente de terminal.restore-history.

Ajustes adicionaisCopiar link

Backup e migraçãoCopiar link

Use Zshell → Exportar Ajustes… para salvar um TOML e Importar Ajustes… para carregá-lo. A importação pede confirmação para substituir e tenta criar config.toml.bak no mesmo diretório.

A importação lê todas as configurações aceitas. Chaves omitidas seguem os padrões do leitor; omitir ai.enabled mantém a opção atual de IA. O idioma e as variáveis de ambiente de projetos e abas são salvos separadamente.

Exemplo completoCopiar link

theme = "dark"
theme-dark = "Catppuccin Mocha"
theme-light = "Catppuccin Latte"
font-family = "IBM Plex Mono"
font-size = 14
interface.scale = 1.25
sidebar.font-size = 13
toolbar.visibility = "auto"
terminal.font-fallback-family = "PingFang SC"
terminal.font-thicken = true
terminal.font-thicken-strength = 180
terminal.line-height = 1.15
terminal.macos-option-as-alt = false
terminal.bell = false
terminal.startup-program = "/opt/homebrew/bin/fish"
terminal.startup-arguments = "--no-config"
terminal.backend = "alacritty"
terminal.restore-history = true
editor.wrap-lines = true
ai.enabled = true
ai.resume-conversations = true

Toda chave é opcional. Exclua uma para restaurar seu padrão.

Atalhos de tecladoCopiar link

Abra Ajustes → Atalhos para gravar uma combinação para um comando principal. O Zshell rejeita conflitos e identifica o comando que já usa a combinação. Restaurar Atalhos Padrão redefine todas as substituições. A referência de teclado lista os padrões.

Ajustes fora deste arquivoCopiar link

• Idioma. Os Ajustes oferecem Padrão do Sistema e 17 idiomas, iguais aos do site. Mudanças se aplicam imediatamente enquanto os terminais continuam rodando. A escolha usa a preferência de idioma por aplicativo do macOS e fica nas preferências Zshell, não no TOML. Padrão do Sistema segue a ordem de idiomas do macOS.
• Atualizações automáticas. As opções de verificar, baixar e instalar em Ajustes → Atualizações usam preferências fora do TOML e persistem entre inicializações. Instalar só aparece quando o download automático está ativado. Veja Instalação.
• Estado de janelas e layout. Tamanho da janela, larguras laterais, painéis selecionados, projetos, abas, painéis de conteúdo, URLs e preferências de diffs ficam nas preferências macOS e no snapshot de sessão.
• Configurações dos backends. O Zshell não lê ~/.config/ghostty nem configurações Alacritty. Os Ajustes Zshell são a interface suportada para ambos.