failproofai README

The project's README from github.com/FailproofAI/failproofai. As one markdown file: README.md.

failproof ai

FailproofAI%2Ffailproofai | Trendshift FailproofAI%2Ffailproofai | Trendshift

npm CI Supply Chain Discord Reddit Docs License

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

Observability and enforcement for every harness your agents run in. Wherever your agents run, we see it — and we can say no. Failproof hooks 12 agent harnesses — coding CLIs like Claude Code and Codex, chat gateways like Hermes, self-hosted assistants like OpenClaw — capturing every run and blocking dangerous tool calls before they execute. 40 built-in policies. Zero latency. Runs locally.

Failproof AI in action

Supported harnesses

Twelve harnesses in two classes — ten coding CLIs, and two chat and assistant gateways (Hermes, OpenClaw). One policy API and one session history across all of them. What a policy can block is per-harness: stopping a tool call before it runs is verified on all twelve, turn-end gates on eight. The per-harness matrix lists the events each one honours.

Agents that run in none of them report through the Python SDK, which gives you tracing, sessions and audits. Enforcement there needs a hook in your own runtime — talk to us and we'll map it.

Claude Code OpenAI Codex GitHub Copilot Cursor Agent OpenCode Pi
Hermes OpenClaw Factory Droid Devin CLI Antigravity CLI Goose

Install

npm install -g failproofai
failproofai config                             # wire up your agents and the daemon
failproofai policies add FailproofAI/policies  # choose what to enforce
failproofai                                    # dashboard on localhost:8020

Setup wires the hooks and picks no policies — that second command is what puts guardrails on the machine, and any pack is typed the same way (failproofai policies add <owner>/<repo>; policies show <owner>/<repo> reads one first). Run failproofai config with no terminal — CI, a container, an agent driving it — and it applies rather than asking. On a machine that has never been set up, any other command runs the same wizard first; disable that with FAILPROOFAI_NO_FIRST_RUN=1.

Until a pack arrives, the only thing enforcing is block-failproofai-commands, which is always on and cannot be switched off or paused: an agent that can pause enforcement can switch off every other policy.

What it stops

Policy What it blocks
block-env-files Reads of .env and other secret files
warn-repeated-tool-calls The agent looping on the same call
block-sudo Privilege escalation
warn-destructive-sql DROP, TRUNCATE, unbounded DELETE
block-terraform / block-kubectl Unreviewed changes to live infrastructure
block-rm-rf Recursive file deletion
block-force-push / block-push-master git push --force, direct pushes to main

Every one of these gates the call before it runs, so they hold on all twelve harnesses. The first four apply to any agent that can call a tool; the last three are the developer favourites — coding CLIs are the harness class we cover deepest. The sanitize-* family is separate: it runs after a tool returns, so it reports a secret in tool output rather than keeping it out of the context.

→ All 40 built-in policies

Your own policies

Drop a file into .failproofai/policies/ — it loads automatically, no flags needed. Commit it and the whole team gets it on next pull.

import { customPolicies, deny, allow } from "failproofai";

customPolicies.add({
  name: "no-production-writes",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolInput?.file_path?.includes("production"))
      return deny("Writes to production paths are blocked.");
    return allow();
  },
});

Three decisions available to every policy:

Decision Effect
allow() Permit the operation
deny(message) Block it — message goes back to the agent
instruct(message) Let it through, but add context to the agent's next prompt

→ Write a policy

Observability

Enforcement is one half. The other half is seeing what the agent actually did.

Run failproofai with no arguments and it serves a dashboard on localhost:8020 reading the run history already on your machine — no account, no signup, nothing leaving the box. You get the session list, the sequence of model calls, tool calls and hook decisions inside each run, what was blocked and what the policy told the agent, and an offline audit (failproofai audit) that scans your history for risky patterns and suggests policies to stop them.

→ Local dashboard · Read a trace · Local audit

Failproof AI Observability is the hosted side of the same data model, for teams running agents across a fleet: every run from every harness in one place, an execution graph with parallel sub-agents on their own lanes, p50/p95/p99 latency for models, tools and hooks, per-model cost and context-window tracking, error tracking, SQL over your own traces with shareable dashboards, evaluations scored by your own service, scheduled audits that turn recurring failures into evidence-backed findings, and alerts routed to Slack, email or a signed webhook. Self-hosting in your own cluster is available on the Enterprise plan.

→ Sessions · Audits · Book a demo

Documentation

Start
Quickstart Install, connect a harness, see the first run
Concepts How the hook system works
Supported harnesses All 12, and what each one can enforce
Observe
Sessions Follow a run: models, tools, errors, latency
Read a trace What the execution graph is telling you
Audits Find failure patterns across many sessions
Local dashboard localhost:8020, no account needed
Enforce
Policy packs The Failproof AI policies, and packs from the policy hub
Write a policy From an audit, or in code
Configuration Config scopes, merge rules and policy parameters
Instrument your own agent
Python SDK Report runs from an agent with no harness
Policy SDK allow / deny / instruct reference

License

MIT with Commons Clause — free for internal and personal use; commercial resale of failproofai itself requires a separate agreement. See LICENSE for the full text.

Contributing

See CONTRIBUTING.md. New policies, edge cases, and translations all welcome.

Build before you start. Run bun install && bun run build first. This repo runs failproofai's own hooks on itself, and they resolve the failproofai import against the compiled dist/ bundle — without a build you'll hit Cannot find package 'failproofai' hook errors. Rebuild after changing src/. See Build before the in-repo dev hooks will work.

Built with ❤️ by befailproof.ai in SF and Bengaluru.

failproofai (FailproofAI/failproofai)

Searching Database…

5.6K ·GitHub
Failproofai
这是干什么用的?Failproof AI 是一个可观测性和执行管控层,内嵌在 AI 代理 harness 里(编码类 CLI、聊天网关、自托管助手),记录每一次运行,并在危险工具调用执行之前拦截它们。
它是命令行工具还是托管的网页面板?它主要是一个本地 CLI/npm 包,接入你的 agent harness,以零额外延迟运行策略;它还会在 localhost:8020 提供一个本地网页面板。另外还有一个独立的托管产品 'Failproof AI Observability',面向在多台机器上跑代理的团队。
怎么把它跑起来?先运行安装命令把钩子接入你的 harness(此时不会启用任何策略),然后再单独添加一个策略包。在没有终端的 CI 或容器里,failproofai config 会自动应用默认配置,而不是交互式提问。
支持哪些编码代理和 harness?共十二种 harness,分两类:十个编码类 CLI(比如 Claude Code 和 Codex),加两个聊天/助手网关(Hermes 和 OpenClaw),它们共用同一套策略 API 和同一条会话历史。
拦截功能在每种 harness 上都一样吗?在工具调用执行前进行拦截,这一点在全部十二种 harness 上都经过验证;但回合结束时的门禁只在其中八种上有效。在这十二种 harness 之外运行的代理,需要用 Python SDK 才能做追踪,而且要实现拦截就得自己给运行时挂钩子。
我的运行数据会离开我的电脑吗?不会 —— 本地面板读取的是已经存在你机器上的运行记录,不需要账号或注册;除非你主动选择使用托管的 Observability 产品,否则任何数据都不会离开你的电脑。
许可证条款是什么?采用 MIT 加 Commons Clause:内部使用和个人使用免费,但对 failproofai 本身进行商业转售需要另外签订协议。
在我做任何配置之前,常开策略就已经拦截什么了?block-failproofai-commands 是唯一一条始终启用、无法禁用也无法暂停的策略,目的就是防止代理用它把其他所有策略都关掉。
怎么写自定义策略?把文件放进 .failproofai/policies/ 文件夹即可,不需要任何参数就会自动加载;提交到代码库后,团队其他人在下次 pull 时就能拿到。策略返回 allow()、deny(message) 或 instruct(message),分别表示放行、拦截或引导代理。
开箱即用能拦住哪些危险操作?40 条内置策略包括:拦截读取 .env 等机密文件、sudo 提权、递归 rm -rf、未经审查的 terraform/kubectl 变更、向 main 强制推送,以及对破坏性 SQL 或重复的工具调用循环给出警告。
托管的 Observability 产品比免费的本地面板多了什么?它把团队里每种 harness 的每次运行汇总在一起,提供并行的子代理执行图、p50/p95/p99 延迟、按模型统计的成本、对追踪数据跑 SQL、定期审计,以及推送到 Slack、邮件或 webhook 的告警;在企业版(Enterprise)方案下还可以自托管到你自己的集群里。
What are similar projects?overmind, opik, evenfire, harness-sdk, Tracely-ai, mission-control, Raven, CowAgent
Which topics is it in?llm-observability, reliability, agent-observability, evals, guardrails, hermes, webhooks, hooks, agent-harness, npm-package, slack, openclaw
Creator
FailproofAI
Size
107.1 MB
Stars
5.6K
Updated
CommitOct 16Releasev1.0.11Oct 16
Age
6mo
Commits · 90 Days