Stitch 2.0 é uma CLI local-first. Ele lê a configuração de CI que já está no seu repositório, roda os mesmos jobs na sua máquina e entrega qualquer falha a um agente de IA (Claude Code ou Codex) para corrigir. Este post é a versão de cinco minutos da documentação.
Pré-requisitos
- Um repositório com um
.gitlab-ci.ymlou um arquivo.github/workflows/*.yml. O Stitch lê qualquer pipeline que você já tenha. - Node 20 ou mais recente (ou Bun, se for o que você usa).
- Claude Code ou Codex instalado e autenticado na sua máquina. Você já tem isso se usa qualquer uma dessas ferramentas no dia a dia.
Essa é a lista completa de dependências. O Stitch não precisa de API key, imagem Docker nem token de plataforma. Ele roda como você, na sua máquina, com o agente que já está logado.
Instalar e rodar
Não tem passo de instalação. O pacote está publicado no npm. Rode diretamente:
npx stitch-agent run claudeOu, se prefere o Codex:
npx stitch-agent run codexNa primeira execução, o Stitch vai detectar qual config de CI você tem, fazer o parse e mostrar os jobs que está prestes a rodar. Jobs de infraestrutura (deploy, publish, release, image pushes) são filtrados automaticamente. Jobs de verificação (lint, typecheck, test, build) são os que rodam localmente.
O terminal muda para uma TUI interativa. Você verá:
- Um stepper de pipeline no topo, passando pelas fases parse, execute e fix.
- Uma tabela de jobs no meio, com status ao vivo por job.
- Um painel do driver na lateral, mostrando o que o agente está fazendo quando uma correção está em andamento.
Você pode assistir ou sair. O Stitch para no primeiro pipeline completo em verde, no teto de tentativas (padrão três por job) ou na primeira coisa que ele decide escalar para você.
O que acontece quando um job falha
O Stitch entrega o job falho para o seu agente com um prompt curto e o contexto relevante. O agente faz o que faz: lê os arquivos no erro, tenta uma correção, manda o Stitch re-executar o job. O Stitch valida rodando o mesmo job de verdade. Se o re-run passa, a tentativa conta como correção. Se falha, o agente tenta de novo, até o teto por job.
O loop é limitado de propósito. Se três tentativas não entregam uma correção, o Stitch para e te mostra o estado: o último diagnóstico, o último patch, o último log. Você assume com contexto completo.
Commit e push
Quando um ciclo de correção termina com todos os jobs verdes, o Stitch pode fazer commit e push do resultado. Isso só acontece se duas condições forem verdadeiras:
- Você estava em um branch limpo quando o Stitch começou. Se havia mudanças sem commit, o Stitch deixa a working tree em paz. Seu trabalho em andamento não é tocado, nunca.
- Você pediu auto-commit. Desligado por padrão. A flag é
--auto-commit.
Isso é conservador de propósito. O jeito mais rápido de perder a confiança numa ferramenta como o Stitch é deixar ela sobrescrever seu trabalho local. Preferimos que você opte por entrar do que ficar se perguntando o que aconteceu.
Modo watch
Para loops de iteração apertados, o Stitch pode ficar rodando e re-verificar quando arquivos mudam:
npx stitch-agent run claude --watchNo modo watch, salvar um arquivo dispara um re-run dos jobs afetados. Você edita, salva, vê verde ou vermelho na TUI em segundos, sem sair do editor. Isso substitui o hábito “dá push para ver se o CI tá feliz” pelo “salva e vê”.
Configuração, se quiser
Zero config é o padrão e dá conta da maioria dos repositórios. Se você quer ajustar o comportamento, coloque um .stitch.yml na raiz do repo:
max_attempts: 3
auto_fix: [lint, format, simple_types, config_ci]
escalate: [logic_errors, breaking_changes, dependency_conflicts]Você não precisa desse arquivo para usar o Stitch. Ele existe para times que querem política explícita.
O que o Stitch não é
O Stitch não substitui seu CI. O pipeline remoto ainda roda no push. O Stitch só te dá uma versão local, mais rápida e assistida por IA da mesma coisa, para você chegar no push com confiança em vez de torcida.
O Stitch não treina no seu código. Não liga para casa. Não há telemetria para desligar porque não há nada reportando em lugar nenhum. Logs e correções ficam locais, a menos que você configure explicitamente um canal de notificação.
O Stitch não precisa de assinatura própria. O único serviço pago no loop é o agente (Claude Code ou Codex), e isso é cobrado na conta que você já tem.
Para onde ir a seguir
O repositório está no GitHub em x24labs/stitch. Issues são acompanhadas lá. O pacote no npm é stitch-agent. O resto está no código e nos posts anteriores desta série, que explicam por que o v2 tem a cara que tem.
Se você experimenta e algo quebra, abra uma issue. O ponto do local-first é que você tem tudo que precisa para reproduzir o problema na sua frente.