https://github.com/exospherehost/failproofai
Create, Manage and Share Hooks for Coding Agents
https://github.com/exospherehost/failproofai
ai claude claude-code coding-agent reliability
Last synced: 9 days ago
JSON representation
Create, Manage and Share Hooks for Coding Agents
- Host: GitHub
- URL: https://github.com/exospherehost/failproofai
- Owner: exospherehost
- License: other
- Created: 2026-04-06T01:56:39.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-28T01:54:40.000Z (16 days ago)
- Last Synced: 2026-04-28T03:32:20.353Z (16 days ago)
- Topics: ai, claude, claude-code, coding-agent, reliability
- Language: TypeScript
- Homepage: https://docs.befailproof.ai
- Size: 20.5 MB
- Stars: 63
- Watchers: 0
- Forks: 4
- Open Issues: 60
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
```
______ _ __ ____ ___ ____
/ ____/___ _(_) /___ _________ ____ / __/ / | / _/
/ /_ / __ `/ / / __ \/ ___/ __ \/ __ \/ /_ / /| | / /
/ __/ / /_/ / / / /_/ / / / /_/ / /_/ / __/ / ___ |_/ /
/_/ \__,_/_/_/ .___/_/ \____/\____/_/ /_/ |_/___/
/_/
```
# Failproof AI
[](https://befailproof.ai)
[](https://www.npmjs.com/package/failproofai)
[](LICENSE)
[](https://github.com/exospherehost/failproofai/actions)
[](https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ)
**Translations**: [简体中文](docs/i18n/README.zh.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) | [Español](docs/i18n/README.es.md) | [Português](docs/i18n/README.pt-br.md) | [Deutsch](docs/i18n/README.de.md) | [Français](docs/i18n/README.fr.md) | [Русский](docs/i18n/README.ru.md) | [हिन्दी](docs/i18n/README.hi.md) | [Türkçe](docs/i18n/README.tr.md) | [Tiếng Việt](docs/i18n/README.vi.md) | [Italiano](docs/i18n/README.it.md) | [العربية](docs/i18n/README.ar.md) | [עברית](docs/i18n/README.he.md)
The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ & the **Agents SDK**.
## Supported agent CLIs
> Install hooks for one or any combination: `failproofai policies --install --cli opencode pi gemini` (or `--cli claude codex copilot cursor opencode pi gemini`). Omit `--cli` to auto-detect installed CLIs and prompt. **GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, and Gemini CLI support are in beta — testing is ongoing.**
- **39 Built-in Policies** - Catch common agent failure modes out of the box. Block destructive commands, prevent secret leakage, keep agents inside project boundaries, detect loops, and more.
- **Custom Policies** - Write your own reliability rules in JavaScript. Use the `allow`/`deny`/`instruct` API to enforce conventions, prevent drift, gate operations, or integrate with external systems.
- **Easy Configuration** - Tune any policy without writing code. Set allowlists, protected branches, thresholds per-project or globally. Three-scope config merges automatically.
- **Agent Monitor** - See what your agents did while you were away. Browse sessions, inspect every tool call, and review exactly where policies fired.
Everything runs locally - no data leaves your machine.
---
## Requirements
- Node.js >= 20.9.0
- Bun >= 1.3.0 (optional - only needed for development / building from source)
---
## Install
```bash
npm install -g failproofai
# or
bun add -g failproofai
```
---
## Quick start
### 1. Enable policies globally
```bash
failproofai policies --install
```
Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke failproofai before and after each tool call.
### 2. Launch the dashboard
```bash
failproofai
```
Opens `http://localhost:8020` - browse sessions, inspect logs, manage policies.
### 3. Check what's active
```bash
failproofai policies
```
---
## Policy installation
### Scopes
| Scope | Command | Where it writes |
|-------|---------|-----------------|
| Global (default) | `failproofai policies --install` | `~/.claude/settings.json` |
| Project | `failproofai policies --install --scope project` | `.claude/settings.json` |
| Local | `failproofai policies --install --scope local` | `.claude/settings.local.json` |
### Install specific policies
```bash
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
```
### Remove policies
```bash
failproofai policies --uninstall
# or for a specific scope:
failproofai policies --uninstall --scope project
```
---
## Configuration
Policy configuration lives in `~/.failproofai/policies-config.json` (global) or `.failproofai/policies-config.json` in your project (per-project).
```json
{
"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"],
"hint": "Use apt-get directly without sudo."
},
"block-push-master": {
"protectedBranches": ["main", "release", "prod"],
"hint": "Try creating a fresh branch instead."
},
"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.mdx](docs/configuration.mdx) for full merge rules.
---
## Built-in policies
| Policy | Description | Configurable |
|--------|-------------|:---:|
| `block-sudo` | Prevent agents from running privileged system commands | `allowPatterns` |
| `block-rm-rf` | Prevent accidental recursive file deletion | `allowPaths` |
| `block-curl-pipe-sh` | Prevent agents from piping untrusted scripts to shell | |
| `block-failproofai-commands` | Prevent self-uninstallation | |
| `sanitize-jwt` | Stop JWT tokens from leaking into agent context | |
| `sanitize-api-keys` | Stop API keys from leaking into agent context | `additionalPatterns` |
| `sanitize-connection-strings` | Stop database credentials from leaking into agent context | |
| `sanitize-private-key-content` | Redact PEM private key blocks from output | |
| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens from output | |
| `block-env-files` | Keep agents from reading .env files | |
| `protect-env-vars` | Prevent agents from printing environment variables | |
| `block-read-outside-cwd` | Keep agents inside project boundaries | `allowPaths` |
| `block-secrets-write` | Prevent writes to private key and certificate files | `additionalPatterns` |
| `block-push-master` | Prevent accidental pushes to main/master | `protectedBranches` |
| `block-work-on-main` | Keep agents off protected branches | `protectedBranches` |
| `block-force-push` | Prevent `git push --force` | |
| `warn-git-amend` | Remind agents before amending commits | |
| `warn-git-stash-drop` | Remind agents before dropping stashes | |
| `warn-all-files-staged` | Catch accidental `git add -A` | |
| `warn-destructive-sql` | Catch DROP/DELETE SQL before execution | |
| `warn-schema-alteration` | Catch ALTER TABLE before execution | |
| `warn-large-file-write` | Catch unexpectedly large file writes | `thresholdKb` |
| `warn-package-publish` | Catch accidental `npm publish` | |
| `warn-background-process` | Catch unintended background process launches | |
| `warn-global-package-install` | Catch unintended global package installs | |
| …and more | | |
Full policy details and parameter reference: [docs/built-in-policies.mdx](docs/built-in-policies.mdx)
---
## Custom policies
Write your own policies to keep agents reliable and on-task:
```js
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:
```bash
failproofai policies --install --custom ./my-policies.js
```
### Decision helpers
| Function | Effect |
|----------|--------|
| `allow()` | Permit the operation |
| `allow(message)` | Permit and send informational context to Claude |
| `deny(message)` | Block the operation; 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 are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.mdx](docs/custom-hooks.mdx) for the full guide.
### Convention-based policies
Drop `*policies.{js,mjs,ts}` files into `.failproofai/policies/` and they're automatically loaded — no flags or config changes needed. Commit the directory to git and every team member gets the same quality standards automatically.
```text
# Project level — committed to git, shared with the team
.failproofai/policies/security-policies.mjs
.failproofai/policies/workflow-policies.mjs
# User level — personal, applies to all projects
~/.failproofai/policies/my-policies.mjs
```
Both levels load (union). Files are loaded alphabetically within each directory. Prefix with `01-`, `02-`, etc. to control order. As your team discovers new failure modes, add a policy and push — everyone gets the update on their next pull. See [examples/convention-policies/](examples/convention-policies/) for ready-to-use examples.
---
## 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:
```bash
FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai
```
---
## Documentation
| Guide | Description |
|-------|-------------|
| [Getting Started](docs/getting-started.mdx) | Installation and first steps |
| [Built-in Policies](docs/built-in-policies.mdx) | All 39 built-in policies with parameters |
| [Custom Policies](docs/custom-policies.mdx) | Write your own policies |
| [Configuration](docs/configuration.mdx) | Config file format and scope merging |
| [Dashboard](docs/dashboard.mdx) | Monitor sessions and review policy activity |
| [Architecture](docs/architecture.mdx) | How the hook system works |
| [Testing](docs/testing.mdx) | Running tests and writing new ones |
### Run docs locally
```bash
docker build -f Dockerfile.docs -t failproofai-docs .
docker run --rm -p 3000:3000 failproofai-docs
```
Opens the Mintlify docs site at `http://localhost:3000`. The container watches for changes if you mount the docs directory:
```bash
docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs
```
---
## Note for failproofai contributors
This repo's `.claude/settings.json` uses `bun ./bin/failproofai.mjs --hook ` instead of the standard `npx -y failproofai` command. This is because running `npx -y failproofai` inside the failproofai project itself creates a self-referencing conflict.
For all other repos, the recommended approach is `npx -y failproofai`, installed via:
```bash
failproofai policies --install --scope project
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
---
## License
See [LICENSE](LICENSE).
---
Built and Maintained by **ExosphereHost: Reliability Research Lab for Your Agents**. We help enterprises and startups improve the reliability of their AI agents through our own agents, software, and expertise. Learn more at [exosphere.host](https://exosphere.host).