Glitch Toolkit

glitch

Uma verificação que parou de recusar coisas ainda passa. É essa a falha que este projeto procura.

Em 8 de setembro de 2026, no repositório do qual este pacote foi extraído, um teste protegia o único capítulo de um livro pago que é disponibilizado gratuitamente — afirmando que a amostra para no corte e não vaza o restante. Estava verde. Estava procurando em uma página que não tinha livro algum, por passagens que, portanto, nunca poderia encontrar, e passando. Nada estava quebrado; a redação funcionava perfeitamente. O alarme havia sido desconectado e ainda mostrava uma luz verde.

Toda proteção decai dessa forma, eventualmente, e a decadência é silenciosa, porque uma proteção que parou de recusar parece exatamente igual a uma que não tem nada a recusar.

glitch instala seis proteções no seu repositório e, sempre que você pedir, executa cada uma contra um caso que ela deveria recusar. Uma que não recusa mais nada falha aqui, ruidosamente, em vez de passar silenciosamente.

pip install glitch-toolkit

glitch install     # put the artifacts in this repository
glitch status      # what is installed, what is not
glitch check --all # verify every step

Sem dependências, sem chamadas de rede, sem telemetria. Não escreve nada fora do diretório que você indicar.

O que ela realmente verifica

Uma etapa não está completa porque um arquivo está presente. Cada verificação faz três coisas e relata quais delas falharam:

1. encontra o artefato
2. executa-o e espera que funcione
3. executa-o contra um caso deliberadamente quebrado e espera que recuse

Sem a terceira, uma verificação passa no momento em que você copia um arquivo, esteja ele com ou sem dentes, e ficaria verde para todos os leitores para sempre. tests/test_cli.py existe para provar que o verificador falha nesse caso; seu teste SABOTAGE instala artefatos que executam, saem com código 0 e não recusam nada.

O que install não fará

Não escreverá seu CLAUDE.md, FLEET.md, FLOOR.md ou PLAN.md. Quatro das seis etapas são verificadas contra o seu próprio arquivo, porque para essas quatro o arquivo é o trabalho: um arquivo de regras que se sustenta, uma mesa com um committer, um piso medido duas vezes, um plano aprovado por outra pessoa. Um comando que os escrevesse transformaria o caminho em "você executou um instalador". Os modelos FLOOR.md e PLAN.md são deliberadamente não-passáveis pela mesma razão.

Não sobrescreverá. Um artefato já presente no seu repositório é deixado intacto e relatado como mantido; --force é como você diz o contrário.

Não escreve nada fora do diretório que você indicar, não faz chamadas de rede e não tem dependências fora da biblioteca padrão.

Executando sem instalá-lo

cli.py é um arquivo e permanece um arquivo. Copie-o para um repositório e status e check funcionam sem nada no PATH e sem etapa de instalação — essa propriedade é deliberada e há um teste para os caminhos de busca que ele usa. Apenas install precisa do restante do pacote, e ele diz isso claramente em vez de falhar de forma estranha.

O servidor MCP (somente leitura)

uvx --from 'glitch-toolkit[mcp]' glitch-mcp --repo .

Instale o extra em um ambiente isolado, não em um Python do sistema. O verificador não tem dependências e isso é uma promessa. O extra [mcp] é o oposto: mcp>=2.0 puxa pydantic, starlette, cryptography, opentelemetry e mais uma dúzia, e o pip atualizará felizmente o que já está lá para satisfazê-los. Feito contra um interpretador global em 8 de setembro de 2026, substituiu pydantic 1.10 por 2.13 e starlette 0.46 por 1.6, quebrando um aplicativo FastAPI não relacionado na mesma máquina. uvx cria um ambiente descartável e não toca em mais nada, por isso a entrada do registro o inicia dessa forma.

Um virtualenv é igualmente adequado:

python -m venv .venv && .venv/bin/pip install 'glitch-toolkit[mcp]'

Ele oferece as verificações a um agente como três ferramentas — glitch_status, glitch_check, glitch_ledger_tail — e anexa cada pergunta e resposta a .claude/toolkit/ledger/ledger.jsonl.

Ele não bloqueia nada. Não pode pausar, bloquear, recusar ou interceptar qualquer ação. Não tem conexão com banco de dados, nenhuma credencial e nenhuma chamada de rede. Essa é toda a primeira versão, de propósito: um servidor que fica entre um agente e um banco de dados de produção é software sério, e a ordem honesta é executar somente leitura primeiro, ler o registro e descobrir o que ele teria recusado antes de dar a ele o poder de recusar. Um bloqueio construído antes de esse registro existir é um palpite com permissões.

As verificações não escrevem nada no seu repositório. O servidor quebra isso em exatamente um lugar — ele anexa ao registro — e --no-ledger desativa até isso, ao custo da única coisa que vale a pena manter.

No Claude Code, .mcp.json:

{
  "mcpServers": {
    "glitch": { "command": "glitch-mcp", "args": ["--repo", "."] }
  }
}

O registro

JSONL somente anexação. Nada reescreve uma linha que acabou de escrever; um registro superado é substituído por um novo e ambos permanecem; um campo que ninguém mediu é null em vez de 0; uma última linha incompleta é ignorada e contada, nunca reparada, porque repará-la significa reescrever o arquivo.

Testes

python tests/run_all.py      # all three suites, 40 tests

A suíte do servidor é ignorada limpidamente sem o extra [mcp] e o executor relata isso como SKIPPED em vez de passar, porque uma linha verde significando "não olhamos" é exatamente a falha que a prática de verificação de bloqueio existe para capturar.

De onde vêm as verificações

Cada verificação aqui existe porque algo deu errado, e CORPUS.md é a lista — o que aconteceu, quanto custou e qual verificação captura isso agora.

Também nomeia as que nada aqui captura ainda, incluindo as duas que custaram a este pacote um número de versão cada. Um corpus que registrasse apenas suas falhas resolvidas estaria fazendo exatamente o que este pacote trata.

Licença

Apache License 2.0 — veja LICENSE e NOTICE. Escolhida em vez de MIT pela concessão de patentes.

Tudo neste repositório está sob ela. Use comercialmente, altere, redistribua.

Os links acima são absolutos de propósito: este README também é a descrição do pacote no PyPI, onde um link relativo resolve contra pypi.org e retorna um 404.

De onde isso vem

Este repositório é um espelho publicado. O pacote é desenvolvido dentro de um monorepo privado junto com o livro Building Your Store Or Your SaaS With Claude, cujas práticas ele instala e verifica, e é enviado aqui como uma subárvore. O livro, a loja que o vende e o restante desse repositório não são open source e não estão aqui. Nada está sendo retido deste repositório que pertença ao pacote.

Issues e pull requests pertencem aqui, não lá, porque aqui é a parte que qualquer um pode ler.

Status

Versão 0.1.1. Instala, e as práticas que verifica são as seis que o livro defende. 0.1.0 foi o primeiro lançamento; 0.1.1 muda esta descrição e adiciona integração contínua, e nada sobre o que o código faz.

O que ainda não é: não bloqueia nada. glitch-mcp relata e registra e não pode impedir um agente de fazer qualquer coisa. Isso é deliberado e o raciocínio está em mcp_server.py — um servidor que fica entre um agente e um banco de dados de produção deve ganhar suas evidências antes de ganhar o poder de recusar.