❓ FAQ - Perguntas Frequentes#

Para diagnóstico técnico mais profundo (comandos de log, causas detalhadas, coleta de informações para bug report), veja 🛠️ Solução de Problemas.

Instalação e Inicialização#

O Codis não abre. O que fazer?#

  1. Verifique o Python 3.12+: python --version
  2. Verifique o Tkinter: python -c "import tkinter" (sem erro = OK)
  3. Rode pelo terminal para ver erros: python run.py
  4. Se houver erro de configuração corrompida, delete ~/.codis/config.json e reinicie

O Codis não requer nenhum pip install para abrir. Se ainda falhar após os passos acima, veja o diagnóstico completo em troubleshooting.md#o-codis-não-abre--tela-preta ou abra uma issue no GitHub com a mensagem de erro completa.

O wizard de primeiro uso não apareceu.#

O wizard só aparece quando first_run_done não está em config.json. Para forçá-lo: delete ~/.codis/config.json e reinicie.

A janela abre mas está em branco ou travada.#

Pode ser sessão corrompida. Delete ~/.codis/session.json e reinicie.

Editor#

O syntax highlighting não funciona para minha linguagem.#

  1. Verifique se a extensão está mapeada em EXT_LANG (src/constants.py)
  2. Mude a linguagem manualmente clicando no nome na barra de status
  3. Se a linguagem não existir no seletor, ela não tem parser implementado - contribuições são bem-vindas!

O autocomplete não aparece.#

  • Verifique autocomplete: true em config.json
  • Aguarde o autocomplete_delay após digitar (padrão: 200 ms)
  • Requer pelo menos autocomplete_min_chars caractere (padrão: 1)

O Ctrl+C / Ctrl+V não funciona em certos contextos.#

O Codis tem um handler global de clipboard contextual:

  • Foco em Entry → opera sobre o campo de texto
  • Foco no editor Text → delega ao handler interno
  • Outros casos → opera sobre o editor ativo

Se não funcionar, verifique qual widget tem foco. Ctrl+A também é contextual.

Interface#

Cliquei num item de menu e parece que nada aconteceu.#

Se a ação correspondente falhar internamente, o Codis mostra um diálogo de erro e registra o problema no log, em vez de simplesmente não fazer nada. Se você vir esse diálogo, copie a mensagem e reporte um bug - ele ajuda bastante a identificar a causa. Se nenhum diálogo aparecer e o item realmente não tiver efeito algum, isso também é um bug válido para reportar.

Temas#

Troquei o tema mas partes ainda têm a cor antiga.#

Use o Modo Completo de troca de tema (não o Modo Rápido) para reconstruir toda a interface com o novo tema.

Como criar um tema?#

Veja Temas → Criando um Tema Customizado.

Linting#

O lint não funciona para Python.#

  1. py_compile (sempre disponível) funciona para erros de sintaxe
  2. Para pylint/mypy/flake8: pip install pylint mypy flake8
  3. Verifique os caminhos em config.json: pylint_path, mypy_path, flake8_path
  4. Confira o Output Panel → canal Python para erros

O ESLint não encontra a configuração do projeto.#

O LintManager executa o ESLint no diretório raiz do workspace. O arquivo de configuração (.eslintrc, eslint.config.js, etc.) deve estar na raiz do workspace aberto.

O lint está lento ou travando o editor.#

O lint roda em thread separada e não deve travar a UI. Se perceber lentidão:

  • Aumente lint_delay em config.json (ex: 1500 ms)
  • Desative linters pesados: "pylint_path": "" ou "lint_python": false
  • Para arquivos grandes: "lint_enabled": false

Terminal#

O terminal não abre / shell não encontrado.#

  1. Verifique se o shell (default_shell) está no PATH
  2. Se em branco, o Codis detecta o primeiro shell disponível automaticamente
  3. No Windows, pelo menos cmd.exe deve estar disponível
  4. Confira o Output Panel para mensagens de erro

Como mudar o shell padrão?#

Ctrl+, → campo default_shell → nome do shell ("bash", "zsh", "PowerShell")
Ou clique no nome do shell na barra de status do terminal.

Git#

O painel Git não detecta meu repositório.#

  1. Verifique se o Git está instalado: git --version
  2. Abra uma pasta que seja repositório Git (contém .git/)
  3. Verifique se git_enabled: true em config.json

Push/Pull falha com erro de autenticação.#

O painel Git exibe um diálogo de credenciais ao detectar erros. Insira seu usuário e token de acesso pessoal (PAT). Para SSH, certifique-se de que a chave SSH está configurada no sistema.

Debug#

Cliquei em Run no Painel de Debug mas o programa roda até o fim sem parar.#

Isso acontece quando nenhum breakpoint foi marcado antes de clicar em Run - sem breakpoints, o debugpy libera a execução e o script roda normalmente do início ao fim. Não é um bug: clique na margem esquerda do editor (gutter), ao lado do número da linha, para marcar um breakpoint antes de iniciar a depuração. Veja o guia completo em Debug.

Erro ao iniciar a depuração / "porta já em uso" / "Address already in use".#

A porta configurada para o DAP (debug_dap_port, padrão 5678) já está sendo usada por outro processo. As causas mais comuns:

  • Outra sessão de debug do Codis ainda está rodando - clique em ⏹ Stop no painel antes de iniciar uma nova.
  • VS Code aberto ao mesmo tempo, depurando Python no mesmo projeto - veja a próxima pergunta.
  • Algum outro processo manual (python -m debugpy ...) deixado rodando em segundo plano.

Solução rápida: mude debug_dap_port para outro valor (ex: 5690) em Configurações → Avançado, ou Ctrl+, → Avançado.

Uso o Codis e o VS Code juntos no mesmo projeto e a depuração de um deles para de funcionar.#

Isso é esperado, não um defeito de nenhum dos dois editores: o Codis e a extensão Python Debugger do VS Code usam, por padrão, exatamente a mesma porta (5678) para conversar com o debugpy, porque os dois seguem a mesma convenção da ferramenta. Com ambos abertos e tentando depurar Python ao mesmo tempo, um deles falha ao abrir a porta, ou acaba conectando à sessão errada.

A solução é simples - não é preciso fechar nenhum dos dois editores:

  1. No Codis, vá em Configurações → Avançado (Ctrl+,);
  2. Mude debug_dap_port para um valor diferente do padrão (ex: 5690, 15678, qualquer porta livre);
  3. Pronto. Os dois editores podem depurar Python ao mesmo tempo, cada um na sua porta, sem disputar o mesmo recurso.

Isso só importa se você for depurar nos dois ao mesmo tempo; usando um por vez nunca há conflito.

debugpy não encontrado no console do painel de Debug.#

Instale com pip install debugpy, no mesmo Python/ambiente virtual que o Codis usa para executar seus scripts (confira o interpretador na barra de status). Sem o debugpy, o painel ainda executa o arquivo, mas sem breakpoints/stepping reais.

Os botões de Step Into/Over/Out/Continue não fazem nada.#

Eles só têm efeito quando a execução está parada num breakpoint (status ⏸ Stopped). Se não houver uma sessão parada (ela ainda não rodou até um breakpoint, já terminou, ou nunca foi iniciada), o painel avisa no console em vez de fingir que algo aconteceu.

LSP#

O LSP não funciona para minha linguagem.#

  1. Instale o servidor LSP (ex: pip install python-lsp-server para Python)
  2. O servidor deve estar no PATH
  3. Verifique o Output Panel → canal LSP para erros
  4. Confirme lsp_enabled: true em config.json

Como verificar se o LSP está ativo?#

Abra um arquivo Python e pressione F12 sobre uma função (Ir para Definição). Se funcionar, o LSP está ativo. Mensagens também aparecem no canal LSP do Output Panel.

K-UI#

O K-UI ativou mas a interface parece bugada.#

  1. Desative com Ctrl+Alt+N
  2. Se não voltar ao normal, reinicie o Codis
  3. Se persistir, delete ~/.codis/config.json para resetar

O K-UI está pesado / lento.#

Mude o perfil de performance para low ou minimal:

  • Ferramentas → K-UI: Performance
  • Spotlight (Ctrl+Space) → "Perf"
Perfil CPU
quantum Muito alto
ultra Alto
high Médio-alto
balanced Médio
windows Médio-baixo
low Baixo
minimal Mínimo (alias de low - ainda tem partículas/meteoros, não é "sem animações")

ultra_plus também existe como alias de quantum, e power_saver como alias de windows (mesmos perfis, nomes alternativos).

As nebulosas não aparecem no K-UI.#

O K-UI usa PIL/Pillow para renderizar as nebulosas em background. Instale com pip install Pillow. Sem PIL, o K-UI usa gradiente puro como fallback.

Criei uma sequência mas o easter egg não ativou.#

Os easter eggs são ativados via comando no terminal integrado: /codis <código>. Exemplo: /codis nova. Ver a lista completa em K-UI → Easter Eggs.

Plugins#

Meu plugin não está sendo carregado.#

  1. Verifique se está em ~/.codis/plugins/
  2. Output Panel → canal Extensions para erros
  3. Verifique se a análise estática de segurança não bloqueou o plugin
  4. Certifique-se de que o plugin define MANIFEST e activate(api)

A análise de segurança bloqueou meu plugin por usar os.#

O analisador de imports (_sandbox_check_imports em src/plugins/api.py) classifica os, pathlib, shutil, requests, threading, pickle e outros como avisos; já subprocess, socket, ssl, ctypes, multiprocessing, winreg e similares são classificados como bloqueados - mais arriscados.

O que acontece depois depende de como o plugin chegou ao Codis:

  • Instalando pela interface (Plugins → Instalar Plugin): tanto avisos quanto bloqueios mostram um diálogo de confirmação. Aceitar adiciona o plugin a ~/.codis/trusted_plugins.json, e ele passa a carregar normalmente nas próximas inicializações.
  • Arquivo já presente em ~/.codis/plugins/ sem nunca ter passado pela instalação (ex: copiado manualmente): se contiver imports bloqueados, é recusado automaticamente, sem diálogo - só passa a carregar depois de ser instalado uma vez pela interface.

Testes#

Como rodar os testes do Codis?#

pip install pytest pytest-cov
pytest tests/ -v

A suíte roda headless (sem display gráfico). Ver tests/README.md.

Os testes falham com erros de importação do Tkinter.#

O conftest.py instala stubs de Tkinter automaticamente antes de qualquer importação. Certifique-se de rodar pytest a partir da raiz do projeto (cd Codis && pytest tests/).

Performance Geral#

O Codis está lento ao abrir arquivos grandes.#

Para arquivos acima de 3 MB, o modo simplificado é ativado automaticamente (syntax highlighting e autocomplete desativados). O limite é configurável via large_file_mb em config.json.

O Codis usa muita memória.#

O conteúdo completo de todos os arquivos abertos fica em memória. Feche abas não utilizadas. O K-UI com perfis ultra ou quantum também consome mais CPU e memória.

Outros#

Como reportar um bug?#

Abra uma issue no GitHub incluindo:

  • Versão do Codis (Ajuda → About Codis)
  • Sistema operacional e versão do Python
  • Passos para reproduzir
  • Mensagens de erro do terminal ou Output Panel

Como contribuir?#

Veja CONTRIBUTING.md.