Skip to content

getting-started.mdx

Latest commit

 

History

History
186 lines (137 loc) · 4.94 KB

getting-started.mdx

File metadata and controls

186 lines (137 loc) · 4.94 KB
title Getting started
description Install failproofai, enable policies, and let your agents run reliably
icon rocket

Requirements

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

Installation

npm install -g failproofai
bun add -g failproofai

Quick start

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. 
```bash
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:

```bash
failproofai policies --install --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
```
```bash failproofai policies ``` 
Shows every policy, whether it's enabled, and any configured parameters.
```bash failproofai ``` 
Opens a local dashboard at `http://localhost:8020` where you can browse sessions, inspect tool calls, and manage policies.
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.

```bash mkdir -p .failproofai/policies ``` Copy the starter examples or write your own: 
```bash
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
```

Or create a new one:

```js
// .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();
  },
});
```
```bash 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:

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

Scopes and config file format All 26 policies with parameters Write your own policies in JavaScript Monitor sessions and review policy activity