______      _ __                       ____   ___    ____
   / ____/___ _(_) /___  _________  ____  / __/  /   |  /  _/
  / /_  / __ `/ / / __ \/ ___/ __ \/ __ \/ /_   / /| |  / /
 / __/ / /_/ / / / /_/ / /  / /_/ / /_/ / __/  / ___ |_/ /
/_/    \__,_/_/_/ .___/_/   \____/\____/_/    /_/  |_/___/
               /_/

Failproof AI

The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for Claude Code & the Agents SDK.

• 26 Built-in Policies - Catch common agent failure modes out of the box. Block destructive commands, prevent secret leakage, keep agents inside project boundaries, detect loops, and more.
• Custom Policies - Write your own reliability rules in JavaScript. Use the allow/deny/instruct API to enforce conventions, prevent drift, gate operations, or integrate with external systems.
• Easy Configuration - Tune any policy without writing code. Set allowlists, protected branches, thresholds per-project or globally. Three-scope config merges automatically.
• Agent Monitor - See what your agents did while you were away. Browse sessions, inspect every tool call, and review exactly where policies fired.

Everything runs locally - no data leaves your machine.

Requirements

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

Install

npm install -g failproofai
# or
bun add -g failproofai

Quick start

1. Enable policies globally

failproofai policies --install

Writes hook entries into ~/.claude/settings.json. Claude Code will now invoke failproofai before and after each tool call.

2. Launch the dashboard

failproofai

Opens http://localhost:8020 - browse sessions, inspect logs, manage policies.

3. Check what's active

failproofai policies

Policy installation

Scopes

Install specific policies

failproofai policies --install block-sudo block-rm-rf sanitize-api-keys

Remove policies

failproofai policies --uninstall
# or for a specific scope:
failproofai policies --uninstall --scope project

Configuration

Policy configuration lives in ~/.failproofai/policies-config.json (global) or .failproofai/policies-config.json in your project (per-project).

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "sanitize-api-keys",
    "block-push-master",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  }
}

Three config scopes are merged automatically (project → local → global). See docs/configuration.mdx for full merge rules.

Built-in policies

Full policy details and parameter reference: docs/built-in-policies.mdx

Custom policies

Write your own policies to keep agents reliable and on-task:

import { customPolicies, allow, deny, instruct } from "failproofai";

customPolicies.add({
  name: "no-production-writes",
  description: "Block writes to paths containing 'production'",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
    const path = ctx.toolInput?.file_path ?? "";
    if (path.includes("production")) return deny("Writes to production paths are blocked");
    return allow();
  },
});

Install with:

failproofai policies --install --custom ./my-policies.js

Decision helpers

Context object (ctx)

Custom hooks support transitive local imports, async/await, and access to process.env. Errors are fail-open (logged to ~/.failproofai/hook.log, built-in policies continue). See docs/custom-hooks.mdx for the full guide.

Telemetry

Failproof AI collects anonymous usage telemetry via PostHog to understand feature usage. No session content, file names, tool inputs, or personal information is ever sent.

Disable it:

FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai

Documentation

Contributing

See CONTRIBUTING.md.

License

See LICENSE.