> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260623-1106.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## Início rápido

<Steps>
  <Step title="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.

    ```bash theme={null}
    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`.

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Verificar">
    ```bash theme={null}
    failproofai policies
    ```

    Exibe todas as políticas, se estão habilitadas e quaisquer parâmetros configurados.
  </Step>

  <Step title="Abrir o painel">
    ```bash theme={null}
    failproofai
    ```

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

  <Step title="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.
  </Step>
</Steps>

***

## Como as políticas funcionam

Toda vez que um agente executa uma ferramenta, o Claude Code chama o failproofai como um subprocesso:

```text theme={null}
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

<Note>
  As políticas rodam no seu processo local. Nada é enviado para um serviço remoto.
</Note>

***

## 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.

<Steps>
  <Step title="Criar o diretório de políticas">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="Adicionar arquivos de política">
    Copie os exemplos iniciais ou escreva os seus próprios:

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

    Ou crie um novo:

    ```js theme={null}
    // .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();
      },
    });
    ```
  </Step>

  <Step title="Commitar no git">
    ```bash theme={null}
    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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

***

## 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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Configuração" icon="gear" href="/pt-br/configuration">
    Escopos e formato do arquivo de configuração
  </Card>

  <Card title="Políticas integradas" icon="shield" href="/pt-br/built-in-policies">
    Todas as 26 políticas com seus parâmetros
  </Card>

  <Card title="Políticas personalizadas" icon="code" href="/pt-br/custom-policies">
    Escreva suas próprias políticas em JavaScript
  </Card>

  <Card title="Monitor de agentes" icon="chart-line" href="/pt-br/dashboard">
    Monitore sessões e revise a atividade das políticas
  </Card>
</CardGroup>