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

Failproof AI

Translations: 简体中文 | 日本語 | 한국어 | Español | Português | Deutsch | Français | Русский | हिन्दी | Türkçe | Tiếng Việt | Italiano | العربية | עברית

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

• 30 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"],
      "hint": "Use apt-get directly without sudo."
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"],
      "hint": "Try creating a fresh branch instead."
    },
    "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.

Convention-based policies

Drop *policies.{js,mjs,ts} files into .failproofai/policies/ and they're automatically loaded — no --custom flag or config changes needed. Works like git hooks: drop a file, it just works.

# Project level — committed to git, shared with the team
.failproofai/policies/security-policies.mjs
.failproofai/policies/workflow-policies.mjs

# User level — personal, applies to all projects
~/.failproofai/policies/my-policies.mjs

Both levels load (union). Files are loaded alphabetically within each directory. Prefix with 01-, 02-, etc. to control order. See examples/convention-policies/ for ready-to-use examples.

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

Run docs locally

docker build -f Dockerfile.docs -t failproofai-docs .
docker run --rm -p 3000:3000 failproofai-docs

Opens the Mintlify docs site at http://localhost:3000. The container watches for changes if you mount the docs directory:

docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs

Note for failproofai contributors

This repo's .claude/settings.json uses bun ./bin/failproofai.mjs --hook <EventType> instead of the standard npx -y failproofai command. This is because running npx -y failproofai inside the failproofai project itself creates a self-referencing conflict.

For all other repos, the recommended approach is npx -y failproofai, installed via:

failproofai policies --install --scope project

Contributing

See CONTRIBUTING.md.

License

See LICENSE.

Built and Maintained by ExosphereHost: Reliability Research Lab for Your Agents. We help enterprises and startups improve the reliability of their AI agents through our own agents, software, and expertise. Learn more at exosphere.host.