zayder 0.3.0

Agente de construção de software que economiza tokens: planner forte + coder barato sobre o Aider, com UI web local

Zayder

Seu agente de construção de software que economiza tokens. Você descreve o que quer em linguagem natural; um modelo forte planeja (e escreve pouco), um modelo barato implementa (e escreve muito), e cada passo é validado por um smoke test e commitado no git — automaticamente.

Por baixo, o Zayder orquestra o Aider com quatro papéis de modelo roteados por custo. Detalhes técnicos: ARCHITECTURE.md.

Instalação

Requisito: só o Git. Não precisa ter Python — o instalador usa o uv, que baixa um Python isolado pra você.

Windows (PowerShell):

irm https://raw.githubusercontent.com/Andrade020/Zayder/main/scripts/install.ps1 | iex

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/Andrade020/Zayder/main/scripts/install.sh | sh

Isso instala o Zayder isolado e (no Windows) cria um atalho Zayder na Área de Trabalho e no Menu Iniciar. Depois é só abrir pelo atalho ou rodar zayder.

Alternativas (já tenho Python/uv/pipx)

uv tool install zayder      # recomendado
pipx install zayder         # alternativa
pip install zayder          # num ambiente seu

Começando em 4 passos

# 1. uma pasta de projeto com git (nova ou existente)
mkdir MeuProjeto; cd MeuProjeto; git init

# 2. abra a interface (ou clique no atalho "Zayder")
zayder

O navegador abre em http://127.0.0.1:8420. Na primeira vez, a tela de Ambiente confere tudo por você (git, chave de API, etc.) e mostra como resolver o que faltar — inclusive com botões de correção.

3. Cole sua chave da DeepSeek no painel ⚙ (fica salva em ~/.zayder/keys.json, fora do projeto — só uma vez).

4. Escreva o objetivo, clique Gerar plano, revise as tarefas (em especial os smoke tests — são o critério de aceite de cada uma) e clique ▶ Aprovar e executar tudo. A partir daí é automático: o Zayder coda, testa, corrige e commita tarefa por tarefa, mostrando log e custo ao vivo. Ele só te interrompe se uma tarefa esgotar as tentativas.

Para conferir o ambiente pelo terminal: zayder doctor --dir .

O que acontece por baixo

Papel	Modelo (default)	Função
Planner	deepseek/deepseek-v4-pro	decompõe o objetivo em tarefas pequenas com spec terso + smoke test
Coder	deepseek/deepseek-v4-flash	escreve o código via Aider e commita (é onde os tokens acontecem — por isso barato)
Coder forte	(opcional)	usado SÓ em tarefas de alto risco; barato no fácil, forte no difícil

Tarefas de alto risco: parsing complexo, ML/lógica temporal, API externa. O Planner marca essas tarefas (caixa "alto risco" no plano) e, se você definir um Coder forte no ⚙, elas vão para ele — o resto continua no Coder barato. Modelo fraco tende a escrever stubs/placeholders nesses módulos; um modelo forte resolve. Com um Coder forte, vale usar edit_format: "diff" (modelos fortes respeitam o formato e gastam menos que reescrever o arquivo inteiro).

• Cada tarefa que passa no smoke é um commit git — git log mostra tudo, git reset --hard <sha> desfaz.
• Logs completos por execução em .zayder/runs/<data-hora>/ (plano, resultado de cada tentativa, custos). Com trace ligado (padrão), há também trace/<tarefa>_a<n>/ com a instrução dada ao Coder, a resposta, o arquivo resultante e a saída completa do smoke — para depurar uma falha sem re-executar (sem gastar tokens).
• Modelos, formato de edição, nº de tentativas e teto de custo são ajustáveis no painel ⚙ ou em .zayder/config.json.

Outros provedores funcionam trocando os modelos (formato litellm: openrouter/..., openai/..., anthropic/...) e colando a chave correspondente — a tela de Ambiente passa a cobrar a chave certa sozinha.

Solução de problemas

• "ambiente incompleto" ao planejar/executar → a tela de Ambiente (ou zayder doctor) lista exatamente o que falta e como resolver.
• "chave de API inválida ou ausente" → confira a chave no painel ⚙; chaves ficam em ~/.zayder/keys.json ou na variável de ambiente (ex. DEEPSEEK_API_KEY).
• Tarefa travou 3 vezes → a UI oferece tentar de novo / pular / abortar. O erro completo está em .zayder/runs/<run>/signals.jsonl.
• ModuleNotFoundError (ex.: pandas) embora a lib esteja instalada → o Zayder está rodando os smokes no Python ERRADO. Veja "usando: …" no painel ⚙: se não for o ambiente onde suas libs vivem, preencha Python dos smokes com o caminho certo (ex.: o python.exe do venv do projeto). O Zayder tenta detectar isso sozinho, mas você manda no override.
• ModuleNotFoundError de pacote realmente ausente → o Zayder instala o pacote 3rd-party automaticamente (pip install no Python configurado) e revalida, sem gastar modelo. Desligue no ⚙ se preferir. Módulos do próprio projeto nunca são instalados via pip.
• ModuleNotFoundError: No module named 'pyaudioop' → você está no Python 3.13+, que removeu o módulo audioop da biblioteca padrão (o aider depende dele via pydub). Instalações novas já resolvem isso sozinhas (o Zayder inclui o audioop-lts no 3.13); se você caiu num ambiente antigo, rode pip install audioop-lts no mesmo ambiente do Zayder. A tela de Ambiente / zayder doctor também sinaliza isso.
• Porta 8420 ocupada → zayder ui --port 8500.

Uso por linha de comando (alternativa à UI)

zayder init --dir .          # cria .zayder/config.json
zayder plan "objetivo..."    # só gera e mostra o plano
zayder run  "objetivo..."    # fluxo completo com aprovação no terminal
zayder run  --plan .zayder/plan.json
zayder doctor                # checa o ambiente

Desenvolvimento

pip install -e ".[dev]"
pytest -q
ruff check zayder tests

Os testes não chamam rede: o orquestrador depende de protocolos e os testes injetam fakes. Licença MIT.