🚀 Primeiros Passos#

Este guia cobre tudo que você precisa para instalar e rodar o Codis pela primeira vez.

Requisitos#

O Codis não possui dependências Python obrigatórias. Funciona com a stdlib pura. Todos os pacotes em requirements.txt são opcionais e ativam funcionalidades extras.

Dependências opcionais#

Nenhuma dessas ferramentas é obrigatória. O Codis funciona sem elas, mas recursos específicos ficam indisponíveis.

Lixeira: Por padrão o Codis move os arquivos excluídos para .codis_trash/ dentro do projeto. Um ícone 🗑 na barra lateral permite restaurar ou excluir permanentemente os arquivos deletados.

Matriz de Compatibilidade#

Python#

Windows#

Requisitos: Python 3.12+ com Tkinter (incluso no instalador oficial) e Visual C++ Redistributable 2015–2022 (para algumas dependências opcionais).

Linux#

# Ubuntu / Debian
sudo apt install python3-tk python3.12 libx11-6 libxft2 libfontconfig1

# Fedora
sudo dnf install python3-tkinter python3.12 libX11 libXft fontconfig

Display: X11 tem suporte completo; Wayland funciona via XWayland com GDK_BACKEND=x11; Wayland puro (sem XWayland) não funciona, pois o Tkinter requer X11.

macOS#

macOS Intel: os runners macos-13 (Intel) foram descontinuados pelo GitHub Actions em janeiro de 2025, portanto não há binário oficial para Intel. Usuários Intel podem compilar localmente com pip install pyinstaller && python package_codis.py pyinstaller.

Requisitos: brew install python@3.12 tcl-tk.

Funcionalidades por plataforma#

Legenda: ✅ Suportado/testado · ⚠️ Funcional com limitações · ❌ Não suportado

Instalação#

# Clonar o repositório
git clone https://github.com/KillovSky/Codis.git
cd Codis

# Executar direto (sem nenhuma dependência extra)
python run.py

# Opcional: instalar pacotes que habilitam funcionalidades extras
pip install -r requirements.txt        # todos os opcionais
pip install send2trash                 # só a lixeira nativa
pip install Pillow markdown            # só K-UI + preview Markdown

Windows: pythonw run.py (sem janela de console)
Linux/macOS: python3 run.py
Alternativo: python -m src

Primeiro Uso - Wizard de Configuração#

Na primeira execução, o Wizard de Primeiro Uso é exibido automaticamente. Ele permite:

• Escolher o tema inicial (Dark, Light, Monokai, Catppuccin etc.)
• Definir o idioma da interface (14 idiomas disponíveis)
• Configurar o shell padrão do terminal integrado
• Ajustar tamanho de fonte e preferências básicas do editor

Após o wizard, as configurações são salvas em ~/.codis/config.json. Para reexibir o wizard, delete config.json e reinicie o Codis.

Abrindo via Linha de Comando#

python run.py caminho/para/arquivo.py           # um arquivo
python run.py caminho/para/minha-pasta/         # workspace
python run.py arquivo1.py arquivo2.js           # múltiplos arquivos

Tela de Boas-Vindas#

Após o wizard (ou nas execuções seguintes), a Tela de Boas-Vindas exibe:

• Ações rápidas: Novo Arquivo, Abrir Arquivo, Abrir Pasta
• Lista de arquivos e pastas recentes (até 20 entradas armazenadas em config.json, mas a Welcome Screen exibe apenas as 12 mais recentes)
• Opção de clonar repositório Git diretamente

Com o K-UI ativo, a tela de boas-vindas transforma-se em um cosmos completo com sistema solar de arquivos, cada arquivo recente orbitando como planeta. Ver K-UI.

A tela pode ser reexibida a qualquer momento via Ajuda → Tela de Boas-Vindas.

Estrutura de Diretórios#

Ao iniciar, o Codis cria automaticamente em ~/.codis/:

~/.codis/
├── config.json          ← Configurações do usuário
├── session.json         ← Sessão (arquivos abertos, workspace)
├── keybindings.json     ← Atalhos personalizados
├── plugins/             ← Plugins instalados
├── snippets/            ← Snippets personalizados por linguagem
├── themes/              ← Criado na inicialização, reservado para uso futuro (não escaneado automaticamente; temas customizados são registrados via plugin com `api.register_theme()`)
├── skills/              ← Skills de IA personalizadas (.md)
├── plugin_data/         ← Storage persistente por plugin
├── trash/               ← Pseudo-lixeira (usada quando send2trash ausente)
├── notes_*.txt          ← Notas de sessão por workspace
└── trusted_plugins.json ← Lista de plugins confiáveis

Restauração de Sessão#

A restauração automática está desativada por padrão. Para ativar:

1. Abra Arquivo → Configurações (Ctrl+,)
2. Ative a opção session_restore

Com ela ativa, o Codis reabrirá automaticamente o workspace e os arquivos da sessão anterior ao reiniciar.

Executando os Testes#

pip install pytest pytest-cov
pytest tests/ -v
pytest tests/ --cov=src --cov-report=term-missing

A suíte roda headless (sem display gráfico), adequada para CI/CD. Ver tests/README.md para documentação completa.

Próximos Passos#

• Interface - conheça o layout completo da UI
• Editor - recursos do editor de código
• Atalhos - referência rápida de atalhos
• K-UI - ative o modo visual holográfico
• Temas - personalize a aparência
• Configurações - todas as opções disponíveis

Modos Standalone#

O Codis permite abrir qualquer módulo individualmente sem iniciar o editor completo. São 29 modos disponíveis (mais 4 aliases).

# Subcomandos diretos (preferido)
python run.py sql              # SQL Studio
python run.py tasks            # Gerenciador de Tarefas (Kanban)
python run.py diff A.py B.py   # Diff Viewer
python run.py paint img.png    # Editor de Imagens
python run.py rest             # REST Client
python run.py regex            # Regex Playground
python run.py terminal .       # Terminal integrado
python run.py git .            # Painel Git
python run.py pip              # Gerenciador de Pacotes Pip
python run.py scratch          # Bloco de Notas (persistido)
python run.py flowchart src/   # Fluxograma AST Python
python run.py render doc.md    # Preview HTML/Markdown/SVG
python run.py stats src/       # Estatísticas de Código
python run.py pomodoro         # Timer Pomodoro
python run.py todo             # Lista de Tarefas Rápidas
python run.py output           # Painel de Output
python run.py processes        # Gerenciador de Processos
python run.py calculator       # Calculadora Científica (alias: calc)
python run.py clock            # Relógio / Alarmes / Cronômetro
python run.py calendar         # Calendário com Lembretes
python run.py env              # Variáveis de Ambiente
python run.py formatter        # Formatador JSON/YAML/TOML/XML
python run.py snippets         # Gerenciador de Snippets
python run.py color-picker     # Seletor de Cores
python run.py player           # Zen Media Player
python run.py accessibility    # Painel de Acessibilidade (alias: a11y)
python run.py plugins          # Gerenciador de Plugins
python run.py ssh              # Conexão SSH Remota
python run.py archive arq.zip  # Visualizador de ZIP/RAR/7z

# Também via python -m src
python -m src sql
python -m src paint

# Flags legadas (ainda funcionam)
python run.py --sql
python run.py --paint

Cada modo carrega apenas as dependências necessárias (tema, i18n, configuração) e abre uma janela autônoma. Fechar a janela encerra o processo.

→ Documentação completa dos modos standalone