{"id":48527917,"url":"https://github.com/exospherehost/failproofai","last_synced_at":"2026-05-05T02:04:42.140Z","repository":{"id":349862565,"uuid":"1202410617","full_name":"exospherehost/failproofai","owner":"exospherehost","description":"Create, Manage and Share Hooks for Coding Agents","archived":false,"fork":false,"pushed_at":"2026-04-28T01:54:40.000Z","size":21490,"stargazers_count":63,"open_issues_count":60,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T03:32:20.353Z","etag":null,"topics":["ai","claude","claude-code","coding-agent","reliability"],"latest_commit_sha":null,"homepage":"https://docs.befailproof.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exospherehost.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-06T01:56:39.000Z","updated_at":"2026-04-28T01:54:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"08b89669-4edf-4217-adb4-ecd263a28e93","html_url":"https://github.com/exospherehost/failproofai","commit_stats":null,"previous_names":["exospherehost/failproofai"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/exospherehost/failproofai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exospherehost%2Ffailproofai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exospherehost%2Ffailproofai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exospherehost%2Ffailproofai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exospherehost%2Ffailproofai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exospherehost","download_url":"https://codeload.github.com/exospherehost/failproofai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exospherehost%2Ffailproofai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32405903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-code","coding-agent","reliability"],"created_at":"2026-04-07T23:03:11.873Z","updated_at":"2026-05-05T02:04:42.126Z","avatar_url":"https://github.com/exospherehost.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n    ______      _ __                       ____   ___    ____\n   / ____/___ _(_) /___  _________  ____  / __/  /   |  /  _/\n  / /_  / __ `/ / / __ \\/ ___/ __ \\/ __ \\/ /_   / /| |  / /\n / __/ / /_/ / / / /_/ / /  / /_/ / /_/ / __/  / ___ |_/ /\n/_/    \\__,_/_/_/ .___/_/   \\____/\\____/_/    /_/  |_/___/\n               /_/\n```\n\n# Failproof AI\n\n[![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://befailproof.ai)\n[![npm](https://img.shields.io/npm/v/failproofai?style=flat-square\u0026color=CB3837)](https://www.npmjs.com/package/failproofai)\n[![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main\u0026style=flat-square\u0026label=CI)](https://github.com/exospherehost/failproofai/actions)\n[![Slack](https://img.shields.io/badge/Slack-join%20us-4A154B?style=flat-square\u0026logo=slack)](https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ)\n\n**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)\n\nThe 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)_ \u0026 the **Agents SDK**.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"failproofai-hq.gif\" alt=\"Failproof AI in action\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n## Supported agent CLIs\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://claude.com/claude-code\" title=\"Claude Code\"\u003e\n    \u003cimg src=\"assets/logos/claude.svg\" alt=\"Claude Code\" width=\"64\" height=\"64\" /\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://developers.openai.com/codex\" title=\"OpenAI Codex\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logos/openai-dark.svg\" /\u003e\n      \u003cimg src=\"assets/logos/openai-light.svg\" alt=\"OpenAI Codex\" width=\"64\" height=\"64\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks\" title=\"GitHub Copilot CLI\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logos/copilot-dark.svg\" /\u003e\n      \u003cimg src=\"assets/logos/copilot-light.svg\" alt=\"GitHub Copilot\" width=\"64\" height=\"64\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://cursor.com/docs/hooks\" title=\"Cursor Agent CLI\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logos/cursor-dark.svg\" /\u003e\n      \u003cimg src=\"assets/logos/cursor-light.svg\" alt=\"Cursor Agent\" width=\"64\" height=\"64\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opencode.ai/docs/plugins/\" title=\"OpenCode\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logos/opencode-dark.svg\" /\u003e\n      \u003cimg src=\"assets/logos/opencode-light.svg\" alt=\"OpenCode\" width=\"64\" height=\"64\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://pi.dev\" title=\"Pi (pi-coding-agent)\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logos/pi-dark.svg\" /\u003e\n      \u003cimg src=\"assets/logos/pi-light.svg\" alt=\"Pi\" width=\"64\" height=\"64\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://geminicli.com/\" title=\"Gemini CLI\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logos/gemini-dark.svg\" /\u003e\n      \u003cimg src=\"assets/logos/gemini-light.svg\" alt=\"Gemini CLI\" width=\"64\" height=\"64\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e 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.**\n\n- **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.\n- **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.\n- **Easy Configuration** - Tune any policy without writing code. Set allowlists, protected branches, thresholds per-project or globally. Three-scope config merges automatically.\n- **Agent Monitor** - See what your agents did while you were away. Browse sessions, inspect every tool call, and review exactly where policies fired.\n\nEverything runs locally - no data leaves your machine.\n\n---\n\n## Requirements\n\n- Node.js \u003e= 20.9.0\n- Bun \u003e= 1.3.0 (optional - only needed for development / building from source)\n\n---\n\n## Install\n\n```bash\nnpm install -g failproofai\n# or\nbun add -g failproofai\n```\n\n---\n\n## Quick start\n\n### 1. Enable policies globally\n\n```bash\nfailproofai policies --install\n```\n\nWrites hook entries into `~/.claude/settings.json`. Claude Code will now invoke failproofai before and after each tool call.\n\n### 2. Launch the dashboard\n\n```bash\nfailproofai\n```\n\nOpens `http://localhost:8020` - browse sessions, inspect logs, manage policies.\n\n### 3. Check what's active\n\n```bash\nfailproofai policies\n```\n\n---\n\n## Policy installation\n\n### Scopes\n\n| Scope | Command | Where it writes |\n|-------|---------|-----------------|\n| Global (default) | `failproofai policies --install` | `~/.claude/settings.json` |\n| Project | `failproofai policies --install --scope project` | `.claude/settings.json` |\n| Local | `failproofai policies --install --scope local` | `.claude/settings.local.json` |\n\n### Install specific policies\n\n```bash\nfailproofai policies --install block-sudo block-rm-rf sanitize-api-keys\n```\n\n### Remove policies\n\n```bash\nfailproofai policies --uninstall\n# or for a specific scope:\nfailproofai policies --uninstall --scope project\n```\n\n---\n\n## Configuration\n\nPolicy configuration lives in `~/.failproofai/policies-config.json` (global) or `.failproofai/policies-config.json` in your project (per-project).\n\n```json\n{\n  \"enabledPolicies\": [\n    \"block-sudo\",\n    \"block-rm-rf\",\n    \"sanitize-api-keys\",\n    \"block-push-master\",\n    \"block-env-files\",\n    \"block-read-outside-cwd\"\n  ],\n  \"policyParams\": {\n    \"block-sudo\": {\n      \"allowPatterns\": [\"sudo systemctl status\", \"sudo journalctl\"],\n      \"hint\": \"Use apt-get directly without sudo.\"\n    },\n    \"block-push-master\": {\n      \"protectedBranches\": [\"main\", \"release\", \"prod\"],\n      \"hint\": \"Try creating a fresh branch instead.\"\n    },\n    \"sanitize-api-keys\": {\n      \"additionalPatterns\": [\n        { \"regex\": \"myco_[A-Za-z0-9]{32}\", \"label\": \"MyCo API key\" }\n      ]\n    },\n    \"warn-large-file-write\": {\n      \"thresholdKb\": 512\n    }\n  }\n}\n```\n\n**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.mdx](docs/configuration.mdx) for full merge rules.\n\n---\n\n## Built-in policies\n\n| Policy | Description | Configurable |\n|--------|-------------|:---:|\n| `block-sudo` | Prevent agents from running privileged system commands | `allowPatterns` |\n| `block-rm-rf` | Prevent accidental recursive file deletion | `allowPaths` |\n| `block-curl-pipe-sh` | Prevent agents from piping untrusted scripts to shell | |\n| `block-failproofai-commands` | Prevent self-uninstallation | |\n| `sanitize-jwt` | Stop JWT tokens from leaking into agent context | |\n| `sanitize-api-keys` | Stop API keys from leaking into agent context | `additionalPatterns` |\n| `sanitize-connection-strings` | Stop database credentials from leaking into agent context | |\n| `sanitize-private-key-content` | Redact PEM private key blocks from output | |\n| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens from output | |\n| `block-env-files` | Keep agents from reading .env files | |\n| `protect-env-vars` | Prevent agents from printing environment variables | |\n| `block-read-outside-cwd` | Keep agents inside project boundaries | `allowPaths` |\n| `block-secrets-write` | Prevent writes to private key and certificate files | `additionalPatterns` |\n| `block-push-master` | Prevent accidental pushes to main/master | `protectedBranches` |\n| `block-work-on-main` | Keep agents off protected branches | `protectedBranches` |\n| `block-force-push` | Prevent `git push --force` | |\n| `warn-git-amend` | Remind agents before amending commits | |\n| `warn-git-stash-drop` | Remind agents before dropping stashes | |\n| `warn-all-files-staged` | Catch accidental `git add -A` | |\n| `warn-destructive-sql` | Catch DROP/DELETE SQL before execution | |\n| `warn-schema-alteration` | Catch ALTER TABLE before execution | |\n| `warn-large-file-write` | Catch unexpectedly large file writes | `thresholdKb` |\n| `warn-package-publish` | Catch accidental `npm publish` | |\n| `warn-background-process` | Catch unintended background process launches | |\n| `warn-global-package-install` | Catch unintended global package installs | |\n| …and more | | |\n\nFull policy details and parameter reference: [docs/built-in-policies.mdx](docs/built-in-policies.mdx)\n\n---\n\n## Custom policies\n\nWrite your own policies to keep agents reliable and on-task:\n\n```js\nimport { customPolicies, allow, deny, instruct } from \"failproofai\";\n\ncustomPolicies.add({\n  name: \"no-production-writes\",\n  description: \"Block writes to paths containing 'production'\",\n  match: { events: [\"PreToolUse\"] },\n  fn: async (ctx) =\u003e {\n    if (![\"Write\", \"Edit\"].includes(ctx.toolName ?? \"\")) return allow();\n    const path = ctx.toolInput?.file_path ?? \"\";\n    if (path.includes(\"production\")) return deny(\"Writes to production paths are blocked\");\n    return allow();\n  },\n});\n```\n\nInstall with:\n\n```bash\nfailproofai policies --install --custom ./my-policies.js\n```\n\n### Decision helpers\n\n| Function | Effect |\n|----------|--------|\n| `allow()` | Permit the operation |\n| `allow(message)` | Permit and send informational context to Claude |\n| `deny(message)` | Block the operation; message shown to Claude |\n| `instruct(message)` | Add context to Claude's prompt; does not block |\n\n### Context object (`ctx`)\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `eventType` | `string` | `\"PreToolUse\"`, `\"PostToolUse\"`, `\"Notification\"`, `\"Stop\"` |\n| `toolName` | `string` | Tool being called (`\"Bash\"`, `\"Write\"`, `\"Read\"`, …) |\n| `toolInput` | `object` | Tool's input parameters |\n| `payload` | `object` | Full raw event payload |\n| `session.cwd` | `string` | Working directory of the Claude Code session |\n| `session.sessionId` | `string` | Session identifier |\n| `session.transcriptPath` | `string` | Path to the session transcript file |\n\nCustom 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.\n\n### Convention-based policies\n\nDrop `*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.\n\n```text\n# Project level — committed to git, shared with the team\n.failproofai/policies/security-policies.mjs\n.failproofai/policies/workflow-policies.mjs\n\n# User level — personal, applies to all projects\n~/.failproofai/policies/my-policies.mjs\n```\n\nBoth 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.\n\n---\n\n## Telemetry\n\nFailproof AI collects anonymous usage telemetry via PostHog to understand feature usage. No session content, file names, tool inputs, or personal information is ever sent.\n\nDisable it:\n\n```bash\nFAILPROOFAI_TELEMETRY_DISABLED=1 failproofai\n```\n\n---\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](docs/getting-started.mdx) | Installation and first steps |\n| [Built-in Policies](docs/built-in-policies.mdx) | All 39 built-in policies with parameters |\n| [Custom Policies](docs/custom-policies.mdx) | Write your own policies |\n| [Configuration](docs/configuration.mdx) | Config file format and scope merging |\n| [Dashboard](docs/dashboard.mdx) | Monitor sessions and review policy activity |\n| [Architecture](docs/architecture.mdx) | How the hook system works |\n| [Testing](docs/testing.mdx) | Running tests and writing new ones |\n\n### Run docs locally\n\n```bash\ndocker build -f Dockerfile.docs -t failproofai-docs .\ndocker run --rm -p 3000:3000 failproofai-docs\n```\n\nOpens the Mintlify docs site at `http://localhost:3000`. The container watches for changes if you mount the docs directory:\n\n```bash\ndocker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs\n```\n\n---\n\n## Note for failproofai contributors\n\nThis repo's `.claude/settings.json` uses `bun ./bin/failproofai.mjs --hook \u003cEventType\u003e` 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.\n\nFor all other repos, the recommended approach is `npx -y failproofai`, installed via:\n\n```bash\nfailproofai policies --install --scope project\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## License\n\nSee [LICENSE](LICENSE).\n\n---\n\nBuilt 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexospherehost%2Ffailproofai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexospherehost%2Ffailproofai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexospherehost%2Ffailproofai/lists"}