Primeiros passos

Instale o failproofai, ative as políticas e deixe seus agentes rodarem de forma confiável

​

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

npm install -g failproofai

bun add -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:

Caminho	O que armazena
~/.failproofai/policies-config.json	Configuração global de políticas
~/.failproofai/hook-activity.jsonl	Histórico de execução de hooks
~/.failproofai/hook.log	Log de depuração para erros de hooks personalizados
.failproofai/policies-config.json	Configuração por projeto (versionada)
.failproofai/policies-config.local.json	Substituiçõ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