Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Requirements

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

​
Installation

npm install -g failproofai

​
Quick start

1

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

Verify

failproofai policies
Shows every policy, whether it’s enabled, and any configured parameters.
3

Launch the dashboard

failproofai
Opens a local dashboard at http://localhost:8020 where you can browse sessions, inspect tool calls, and manage policies.
4

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.

​
How policies work

Every time an agent runs a tool, Claude Code calls failproofai as a subprocess: 
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
Policies run in your local process. Nothing is sent to a remote service.

​
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.
1

Create the policies directory

mkdir -p .failproofai/policies
2

Add policy files

Copy the starter examples or write your own:
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
Or create a new one:
// .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

Commit to git

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

​
Data storage

All configuration and logs stay on your machine:
PathWhat it stores
~/.failproofai/policies-config.jsonGlobal policy config
~/.failproofai/hook-activity.jsonlHook execution history
~/.failproofai/hook.logDebug log for custom hook errors
.failproofai/policies-config.jsonPer-project config (committed)
.failproofai/policies-config.local.jsonPersonal overrides (gitignored)

​
Uninstalling

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

​
Next steps

Configuration

Scopes and config file format

Built-in policies

All 26 policies with parameters

Custom policies

Write your own policies in JavaScript

Agent monitor

Monitor sessions and review policy activity