Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (failproofai) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Failproof AI

Open-source hooks, policies, and project visualization for Claude Code & the Agents SDK.

Hooks & Policies — 35+ built-in security policies that run as Claude Code hooks. Block dangerous commands, sanitize secrets, restrict file access, and more.
Custom Policies — Write your own policies in JavaScript. Same allow/deny/instruct API as built-in policies, with full async support.
Policy Parameters — Tune built-in policies without writing code: configure allowlists, protected branches, thresholds, and custom patterns.
Session Viewer — Browse Claude Code projects and sessions locally. Inspect tool calls, messages, and per-session hook activity side-by-side.

Everything runs locally — no data leaves your machine.

Requirements

Node.js >= 20.9.0
Bun >= 1.3.0

Install

npm install -g failproofai

Quick start

1. Enable policies globally

failproofai --install-policies

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 --list-policies

Policy installation

Scopes

Scope	Command	Where it writes
Global (default)	`failproofai --install-policies`	`~/.claude/settings.json`
Project	`failproofai --install-policies --scope project`	`.claude/settings.json`
Local	`failproofai --install-policies --scope local`	`.claude/settings.local.json`

Install specific policies

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

Remove policies

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

Configuration

Policy configuration lives in ~/.failproofai/hooks-config.json (global) or .failproofai/hooks-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.md for full merge rules.

Built-in policies

Policy	Description	Configurable
`block-sudo`	Block sudo commands	`allowPatterns`
`block-rm-rf`	Block recursive deletions	`allowPaths`
`block-curl-pipe-sh`	Block curl\|bash and wget\|bash
`block-failproofai-commands`	Prevent self-uninstallation
`sanitize-jwt`	Redact JWT tokens from tool output
`sanitize-api-keys`	Redact API keys from tool output	`additionalPatterns`
`sanitize-connection-strings`	Redact database credentials from tool output
`sanitize-private-key-content`	Redact PEM private key blocks
`sanitize-bearer-tokens`	Redact Authorization Bearer tokens
`block-env-files`	Block access to .env files
`protect-env-vars`	Block commands that print environment variables
`block-read-outside-cwd`	Block reading files outside the project	`allowPaths`
`block-secrets-write`	Block writes to private key and certificate files	`additionalPatterns`
`block-push-master`	Block pushing to main/master	`protectedBranches`
`block-work-on-main`	Block checking out main/master	`protectedBranches`
`block-force-push`	Block `git push --force`
`warn-git-amend`	Warn on `git commit --amend`
`warn-git-stash-drop`	Warn on `git stash drop`
`warn-all-files-staged`	Warn on `git add -A`
`warn-destructive-sql`	Warn on DROP/DELETE SQL statements
`warn-schema-alteration`	Warn on ALTER TABLE statements
`warn-large-file-write`	Warn on large file writes	`thresholdKb`
`warn-package-publish`	Warn on `npm publish`
`warn-background-process`	Warn on background process launches
`warn-global-package-install`	Warn on global package installs
…and more

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

Custom policies

Create a .js file with your own policies:

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 --install-policies --custom-hooks ./my-policies.js

Decision helpers

Function	Effect
`allow()`	Permit the tool call
`deny(message)`	Block the tool call; message shown to Claude
`instruct(message)`	Add context to Claude's prompt; does not block

Context object (`ctx`)

Field	Type	Description
`eventType`	`string`	`"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"`
`toolName`	`string`	Tool being called (`"Bash"`, `"Write"`, `"Read"`, …)
`toolInput`	`object`	Tool's input parameters
`payload`	`object`	Full raw event payload
`session.cwd`	`string`	Working directory of the Claude Code session
`session.sessionId`	`string`	Session identifier
`session.transcriptPath`	`string`	Path to the session transcript file

Custom hooks support transitive local imports, async/await, and access to process.env. Errors in custom hooks are fail-open (logged to ~/.failproofai/hook.log, built-in policies continue). See docs/custom-hooks.md 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

Guide	Description
Getting Started	Installation and first steps
CLI Reference	All commands and flags
Configuration	Config file format and scope merging
Built-in Policies	All 35+ policies with parameters
Custom Hooks	Write your own policies
Dashboard	Session viewer and policy management
Architecture	How the hook system works
Testing	Running tests and writing new ones

Contributing

See CONTRIBUTING.md.

License

See LICENSE.

failproofai