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

npm

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 Claude Code’s settings.json. You can also install for a single project or pick specific policies:

   failproofai policies --install --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.

---

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

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 hooks

Write your own policies in JavaScript

Agent monitor

Monitor sessions and review policy activity