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

# Getting started

> Install failproofai, enable policies, and let your agents run reliably

## Requirements

* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (optional - only needed for building from source)

***

## Installation

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

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

***

## Quick start

<Steps>
  <Step title="Enable policies">
    Policies are rules that run before and after every agent tool call. They catch destructive commands, secret leakage, and other failure modes before they cause damage.

    ```bash theme={null}
    failproofai policies --install
    ```

    This writes hook entries into your installed agent CLIs (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generated plugin shim at `~/.config/opencode/plugins/failproofai.mjs` plus a registration entry in `~/.config/opencode/opencode.json`'s `plugin` array, Pi's `~/.pi/agent/settings.json`, or Gemini CLI's `~/.gemini/settings.json`). When more than one is present you'll be prompted; pass `--cli claude codex copilot cursor opencode pi gemini` (any subset) to skip the prompt.

    GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, and Gemini CLI support are **beta** — install with `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, or `--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="Verify">
    ```bash theme={null}
    failproofai policies
    ```

    Shows every policy, whether it's enabled, and any configured parameters.
  </Step>

  <Step title="Launch the dashboard">
    ```bash theme={null}
    failproofai
    ```

    Opens a local dashboard at `http://localhost:8020` where you can browse sessions, inspect tool calls, and manage policies.
  </Step>

  <Step title="Run your agent">
    Start Claude Code as usual. If the agent tries something risky, failproofai intercepts it automatically. Leave it running unattended and review what happened in the dashboard.
  </Step>
</Steps>

***

## How policies work

Every time an agent runs a tool, Claude Code calls failproofai as a subprocess:

```text theme={null}
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
```

Each policy returns one of three decisions:

* **allow** - the agent proceeds normally
* **deny** - the action is blocked, the agent is told why
* **instruct** - extra context is added to the agent's prompt

<Note>
  Policies run in your local process. Nothing is sent to a remote service.
</Note>

***

## Set up team policies with convention-based policies

The fastest way to establish quality standards across your team is the `.failproofai/policies/` convention. Drop policy files into this directory and they're loaded automatically — no flags, no config changes, no install commands.

<Steps>
  <Step title="Create the policies directory">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="Add policy files">
    Copy the starter examples or write your own:

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

    Or create a new one:

    ```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="Commit to git">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

    Every team member who has failproofai installed picks up these policies automatically. No per-developer setup needed.
  </Step>
</Steps>

<Tip>
  Commit `.failproofai/policies/` to your repo so the whole team shares the same standards. As your team discovers new failure modes, add policies and push — everyone gets the update on their next `git pull`. Over time these policies become a living quality standard that keeps improving.
</Tip>

***

## Data storage

All configuration and logs stay on your machine:

| Path                                      | What it stores                   |
| ----------------------------------------- | -------------------------------- |
| `~/.failproofai/policies-config.json`     | Global policy config             |
| `~/.failproofai/hook-activity.jsonl`      | Hook execution history           |
| `~/.failproofai/hook.log`                 | Debug log for custom hook errors |
| `.failproofai/policies-config.json`       | Per-project config (committed)   |
| `.failproofai/policies-config.local.json` | Personal overrides (gitignored)  |

***

## Uninstalling

```bash theme={null}
failproofai policies --uninstall
```

Removes hook entries from `~/.claude/settings.json`. Config files in `~/.failproofai/` are kept.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration">
    Scopes and config file format
  </Card>

  <Card title="Built-in policies" icon="shield" href="/built-in-policies">
    All 26 policies with parameters
  </Card>

  <Card title="Custom policies" icon="code" href="/custom-policies">
    Write your own policies in JavaScript
  </Card>

  <Card title="Agent monitor" icon="chart-line" href="/dashboard">
    Monitor sessions and review policy activity
  </Card>
</CardGroup>