ai-engineering-guardrails

AI Engineering Guardrails

AI Engineering Guardrails is a local, vendor-neutral toolkit for applying consistent guidance, skills and narrow checks across OpenAI Codex, Claude Code, Cursor, GitHub Copilot in VS Code and Visual Studio, and JetBrains AI Assistant/Copilot.

It renders one canonical policy for each supported product. Its deliberately limited aim is to help agents inspect first, preserve user work, avoid secrets and destructive operations, verify changes, and report what happened. Think of it as a seatbelt, not a committee meeting.

The short version

• One canonical policy, rendered for six product surfaces rather than copied six times.
• Narrow deterministic checks for high-confidence risks: destructive Git operations, publication, credential exposure, and dangerous infrastructure actions.
• Portable, on-demand skills and capability packs for application, delivery, and infrastructure work.
• A local installer that preserves unrelated configuration, creates backups, and uses an immutable runtime independent of the source clone.
• Optional offline assurance for policy evidence, bounded task contracts, imported test/report summaries, and local instruction or skill review.
• Optional routing and terminal UX—both off unless you explicitly enable them.

This is defence in depth, not a replacement for product approvals, sandboxing, operating-system permissions, branch protection, cloud IAM, Kubernetes RBAC, or a human release decision.

Start here

Python 3.11+ is required. Install the published package with pipx and preview before writing anything. Do not use sudo, Administrator, or an elevated shell.

pipx install ai-engineering-guardrails

ai-guardrails install --dry-run
ai-guardrails install
ai-guardrails status

For contributor work or a reviewed local checkout instead:

git clone https://github.com/ZarrenSpryXplor/ai-engineering-guardrails.git
cd ai-engineering-guardrails
pipx install .

The default install detects local supported products, uses no cloud login, and changes no main model, approval setting, sandbox, network setting, routing profile, or terminal decoration. If no product is detected, it makes no change and prints the explicit command to use.

For a direct Git install, pin a reviewed tag or full commit rather than a moving branch:

pipx install 'git+https://github.com/ZarrenSpryXplor/ai-engineering-guardrails.git@<reviewed-tag-or-full-commit>'

The package is published on PyPI through Trusted Publishing. Maintainers should follow the release guide for protected approvals, version/tag checks, and provenance.

Optional extras

Terminal visibility is opt-in. Claude Code can use a managed local status line; Codex uses its native /statusline fields; Cursor CLI keeps its documented /status-indicators control.

ai-guardrails statusline preview --product all --profile standard
ai-guardrails statusline install --product all --profile standard --dry-run
ai-guardrails statusline install --product all --profile standard
ai-guardrails activity --since 24h
ai-guardrails receipt --compact

Routing is also opt-in. It installs static, bounded roles; it does not classify prompts, choose a model at runtime, or grant authority.

ai-guardrails routing show --profile balanced --product codex
ai-guardrails routing set balanced --product codex --dry-run
ai-guardrails routing set balanced --product codex

Assurance tools stay local and offline. They inspect metadata, repository state, supplied reports, and bounded component files; they do not run analyzers, execute downloaded instructions, or award a magical “all bugs gone” sticker.

ai-guardrails policy audit
ai-guardrails task init --repo . --dry-run
ai-guardrails component inspect ./reviewed-skill
ai-guardrails skills audit
ai-guardrails docs audit --path README.md

See evidence and assurance for task setup, report comparison, trust records, and the limits of each result.

Find the right detail

The operator documentation hub is the durable entry point. It gives each audience one place to start instead of making this README do every job.

Contribute and report safely

• Read CONTRIBUTING.md before changing canonical policy, generated output, or product integration.
• Report vulnerabilities privately using SECURITY.md; do not put exploit details or secrets in a public issue.
• See CHANGELOG.md for release-facing changes and CODE_OF_CONDUCT.md for community expectations.

The project is MIT licensed. It makes no claim to be a universal security boundary or to save a particular amount of money, time, or tokens.