faq

❓ 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.