Configuration

Documentation Index

Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Configuration scopes

​

Merge rules

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplicated union

project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project wins, global ignored

project:  (no block-sudo entry)
local:    (no block-sudo entry)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← falls through to global

​

Config file format

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "sanitize-jwt",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "block-rm-rf": {
      "allowPaths": ["/tmp"]
    },
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  },
  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
}

​

Field reference

​

enabledPolicies

​

policyParams

​

hint (cross-cutting)

{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}

​

customPoliciesPath

​

Convention-based policies

​

llm

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​

Managing configuration from the CLI

• Agent CLI settings — tells the agent to call failproofai --hook <event> on each tool use:
  • Claude Code: ~/.claude/settings.json (user), <cwd>/.claude/settings.json (project), <cwd>/.claude/settings.local.json (local)
  • OpenAI Codex: ~/.codex/hooks.json (user), <cwd>/.codex/hooks.json (project) — Codex doesn’t have a local scope
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (user), <cwd>/.github/hooks/failproofai.json (project) — Copilot has no local scope. Hook entries use Copilot’s OS-keyed bash/powershell command fields with timeoutSec; the file carries a top-level version: 1 marker. Copilot CLI support is beta while we verify the events.jsonl record schema (which the public docs do not specify) against more real-world sessions.
  • Cursor Agent (beta): ~/.cursor/hooks.json (user), <cwd>/.cursor/hooks.json (project) — Cursor has no local scope. Hook entries use the Claude-shaped {type, command, timeout} form (no bash/powershell split), but stored under camelCase event keys (preToolUse, beforeSubmitPrompt, …) in a flat array per Cursor’s hooks schema; the file carries a top-level version: 1 marker. The handler canonicalizes camelCase → PascalCase via CURSOR_EVENT_MAP so existing builtin policies fire unchanged. Cursor Agent support is beta while we verify Cursor’s transcript on-disk format (not specified in the public docs) against more real-world installs.
  • OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (user), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (project) — OpenCode has no local scope. Unlike the other six CLIs, OpenCode has no external-command hook system: it loads in-process JS/TS plugins explicitly registered via the plugin: [] array in opencode.json (auto-discovery from .opencode/plugins/ is not how plugins load on opencode v1.14.33). Install drops a small generated plugin shim that subprocess-calls the failproofai binary and translates the binary’s Claude-shape JSON response back into plugin semantics: throw new Error() for tool-event deny (cancels the tool call), client.session.prompt(...) for instruct AND for Stop / SubagentStop deny (submits the deny reason as the next user message — the only force-retry channel since session.idle is notification-only and throwing from it is a no-op), and no-op for allow. The shim canonicalizes both tool names (lowercase → PascalCase via OPENCODE_TOOL_MAP) and tool-input arg keys (camelCase → snake_case via OPENCODE_TOOL_INPUT_MAP for Read / Write / Edit, e.g. filePath → file_path, oldString → old_string) before forwarding to the binary, so path-checking builtins like block-read-outside-cwd, block-env-files, and block-secrets-write fire unchanged on OpenCode tool calls. Sessions live in opencode’s SQLite DB at ~/.local/share/opencode/opencode.db; the dashboard’s session viewer reads them via opencode db --format json and opencode export <id>. OpenCode support is beta while we verify behavior across versions and against more real-world sessions. See the OpenCode plugins docs.
  • Pi (beta): ~/.pi/agent/settings.json (user), <cwd>/.pi/settings.json (project) — Pi has no local scope. Pi loads TypeScript extension packages at startup; the settings file is a flat string array {"packages": ["./relative/path", …]}. failproofai writes a single packages-array entry pointing at its bundled pi-extension/ directory. The extension internally subscribes to Pi’s tool_call / user_bash / input / session_start events and shells out to failproofai --hook <Event> --cli pi; the handler canonicalizes underscore_lower_snake_case → PascalCase via PI_EVENT_MAP so existing builtin policies fire unchanged. Tool input args are also canonicalized via PI_TOOL_INPUT_MAP (Pi’s Read / Write / Edit deliver path rather than file_path; mapping the top-level key lets block-env-files and block-secrets-write fire — block-read-outside-cwd already had a path fallback). Pi support is beta while Pi’s extension API and session-log layout stabilize.
  • Gemini CLI (beta): ~/.gemini/settings.json (user), <cwd>/.gemini/settings.json (project) — Gemini has no local scope (it documents a system scope at /etc/gemini-cli/settings.json which failproofai does not expose). Hook entries use Claude’s {type, command, timeout} form wrapped in Gemini’s {matcher, hooks: [...]} matcher schema with matcher: "*" by default. Events are PascalCase (SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd); the handler maps to Claude canonical names via GEMINI_EVENT_MAP. Tool names are snake_case (run_shell_command, read_file, write_file, replace, …) — the handler canonicalizes via GEMINI_TOOL_MAP so existing builtin policies fire unchanged. The policy evaluator emits Gemini’s flat {decision: "deny", reason} shape (preferred per Gemini’s “Golden Rule” exit-0 contract), {hookSpecificOutput: {hookEventName, additionalContext}} for context injection on BeforeAgent / AfterTool / SessionStart, and {decision: "block", reason} on AfterAgent for force-retry semantics. Gemini CLI support is beta while we widen real-world coverage. See the Gemini CLI hooks docs.
• policies-config.json — tells failproofai which policies to evaluate and with what params (shared across all agent CLIs)

failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli gemini --scope project
failproofai policies --install --cli claude codex copilot cursor opencode pi gemini

• One CLI detected — auto-selects that CLI without prompting.
• Multiple CLIs detected in an interactive terminal — shows an arrow-key single-select prompt grouped into a Detected (N) section (with an Install for all N detected aggregate row + each detected CLI individually) and a Not installed (M) · install hooks ahead of time section listing every undetected supported CLI as a forward-install option (↑↓ to move, Enter to select, ^C to quit). The uninstall flow shows only the Detected section.
• Multiple CLIs detected in a non-interactive run (CI, no TTY) — installs for all detected CLIs without prompting.
• None detected — falls back to claude, with a warning that no agent binary was found in PATH; the hook command is still written so it activates as soon as you install one.

​

Example: project-level config with team defaults

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}