Pular para o conteúdo principal

​
Requisitos

  • Node.js >= 20.9.0
  • Bun >= 1.3.0 (opcional - necessário apenas para compilar a partir do código-fonte)

​
Instalação

npm install -g failproofai

​
Início rápido

1

Ativar políticas

Políticas são regras que executam antes e depois de cada chamada de ferramenta do agente. Elas interceptam comandos destrutivos, vazamento de segredos e outros modos de falha antes que causem danos.
failproofai policies --install
Isso grava entradas de hook nos CLIs de agentes instalados (o ~/.claude/settings.json do Claude Code, o ~/.codex/hooks.json do OpenAI Codex, o ~/.copilot/hooks/failproofai.json do GitHub Copilot CLI, o ~/.cursor/hooks.json do Cursor Agent, o shim de plugin gerado pelo OpenCode em ~/.config/opencode/plugins/failproofai.mjs mais uma entrada de registro no array plugin do ~/.config/opencode/opencode.json, o ~/.pi/agent/settings.json do Pi, ou o ~/.gemini/settings.json do Gemini CLI). Quando mais de um estiver presente, você será solicitado a escolher; passe --cli claude codex copilot cursor opencode pi gemini (qualquer subconjunto) para pular a confirmação.O suporte ao GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI está em beta — instale com --cli copilot, --cli cursor, --cli opencode, --cli pi ou --cli gemini.
failproofai policies --install --scope project
failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli gemini --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
2

Verificar

failproofai policies
Exibe todas as políticas, se estão habilitadas e quaisquer parâmetros configurados.
3

Abrir o painel

failproofai
Abre um painel local em http://localhost:8020 onde você pode navegar pelas sessões, inspecionar chamadas de ferramentas e gerenciar políticas.
4

Executar seu agente

Inicie o Claude Code normalmente. Se o agente tentar algo arriscado, o failproofai o intercepta automaticamente. Deixe-o rodando sem supervisão e revise o que aconteceu no painel.

​
Como as políticas funcionam

Toda vez que um agente executa uma ferramenta, o Claude Code chama o failproofai como um subprocesso: 
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
Cada política retorna uma de três decisões:
  • allow - o agente prossegue normalmente
  • deny - a ação é bloqueada e o agente é informado do motivo
  • instruct - contexto adicional é inserido no prompt do agente
As políticas rodam no seu processo local. Nada é enviado para um serviço remoto.

​
Configure políticas para a equipe com políticas baseadas em convenção

A maneira mais rápida de estabelecer padrões de qualidade em toda a equipe é a convenção .failproofai/policies/. Coloque arquivos de política nesse diretório e eles são carregados automaticamente — sem flags, sem alterações de configuração, sem comandos de instalação.
1

Criar o diretório de políticas

mkdir -p .failproofai/policies
2

Adicionar arquivos de política

Copie os exemplos iniciais ou escreva os seus próprios:
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
Ou crie um novo:
// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
      return instruct("Run tests before committing.");
    }
    return allow();
  },
});
3

Commitar no git

git add .failproofai/policies/
git commit -m "Add team quality policies"
Todo membro da equipe que tiver o failproofai instalado receberá essas políticas automaticamente. Nenhuma configuração por desenvolvedor é necessária.
Faça commit de .failproofai/policies/ no seu repositório para que toda a equipe compartilhe os mesmos padrões. À medida que a equipe descobre novos modos de falha, adicione políticas e faça push — todos recebem a atualização no próximo git pull. Com o tempo, essas políticas se tornam um padrão de qualidade vivo que continua melhorando.

​
Armazenamento de dados

Todas as configurações e logs ficam na sua máquina:
CaminhoO que armazena
~/.failproofai/policies-config.jsonConfiguração global de políticas
~/.failproofai/hook-activity.jsonlHistórico de execução de hooks
~/.failproofai/hook.logLog de depuração para erros de hooks personalizados
.failproofai/policies-config.jsonConfiguração por projeto (versionada)
.failproofai/policies-config.local.jsonSubstituições pessoais (ignoradas pelo git)

​
Desinstalação

failproofai policies --uninstall
Remove as entradas de hook do ~/.claude/settings.json. Os arquivos de configuração em ~/.failproofai/ são mantidos.

​
Próximos passos

Configuração

Escopos e formato do arquivo de configuração

Políticas integradas

Todas as 26 políticas com seus parâmetros

Políticas personalizadas

Escreva suas próprias políticas em JavaScript

Monitor de agentes

Monitore sessões e revise a atividade das políticas