⚠️ Early release: APIs may change before 1.0.
Your agent just tried cat .env. It got back the keys — not the values — and kept working.
That's the whole idea: a steering layer for AI coding agents. Instead of stopping the agent cold, rules hand it a safer or better move it can act on immediately — suggest a redacted read, run a rewritten command, redact a leaked value, confirm with a human, or block when nothing safe exists.
Rules work out of the box — no config, no flags:
npm install guiderailsUsing Pi? Register the extension and you're done:
import piGuiderails from "guiderails/adapters/pi";
export default piGuiderails;Try cat .env in your agent — it comes back with a redacted read instead of the raw file. A stricter posture is on the roadmap: --strict will confirm-gate anything secret-shaped even without a specific rule and lock the hardening pack on (ADR-007).
-
Pi plugin — in-process, ships today. Register as shown above (adapter docs).
-
TypeScript library — building your own harness?
npm install guiderails, one function:import { createEngine, loadAllRulePacks } from "guiderails"; const engine = createEngine(loadAllRulePacks("./packs", registry), capabilities); const action = engine.evaluate(ctx); // per tool call / tool result / user prompt
-
Claude Code hooks — on the roadmap; not shipped yet.
Security — fires rarely, saves your week when it does:
| Pack | What it does |
|---|---|
env |
.env reads come back redacted — keys visible, values gone |
sops |
sops -d swapped for a format-aware redacted pipe |
private-key |
.pem, .key, SSH key reads blocked |
secret-managers |
pass show, op read, gopass, bw get blocked — nothing safe to transform into |
encryption-tools |
age -d, gpg --decrypt, openssl enc -d blocked |
hardening |
shell wrappers (eval, bash -c, $()) around risky commands force-blocked |
Status: the packs above are the v0.1.0 shipping set; anything not listed here doesn't exist yet and isn't claimed. Steering packs (modern-cli, package-manager, git-safety) are on the roadmap.
Every boundary where a secret can cross into the model's context is mediated: user input (a key pasted into the prompt is scrubbed before it reaches the API), tool calls, and tool output.
Agent Tool Call → Match Rules → Resolve Action → Enforce
↓ ↓ ↓ ↓
ToolCallContext Rule Packs GuardrailAction Harness Specific
(YAML) + Fallback Chain Behaviour
Rules are YAML (plus TypeScript predicates for complex logic). Each adapter declares what its harness can do (HarnessCapabilities); when a capability is missing, the engine degrades deterministically (run → suggest → block, confirm → block, redact → block) — declared, never silent. Details in the ADRs.
- Built-in rules can be locked (
overridable: false) so no user config softens them; community packs can't claim that privilege. - Unmatched calls fail open (the agent keeps working); an engine crash fails closed (
block), unconditionally, on every adapter. - Whether the layer runs somewhere the agent could tamper with it is a declared per-adapter fact (
tamperResistant), not a hand-wave.
See ADR-007 and LIMITATIONS.md.
- Pi — first-party, in-process plugin for Pi
- Claude Code — first-party, external hooks (roadmap)
- Community adapters welcome — any harness integrates against the stable adapter interface (ADR-009, ADR-003)
- Getting Started — install, capability table, embedding quickstart, architecture
- Rule Pack Guide — complete YAML format spec with steering and security examples
- Pack Gallery — every shipped pack and rule, auto-generated
- How Matching Works — layer-by-layer walkthrough
- ADRs — the why behind core design choices
- LIMITATIONS.md · SECURITY.md
We welcome rule packs, community adapters, and engine improvements. See CONTRIBUTING.md — the lowest-friction contribution is a YAML rule pack.
MIT — see LICENSE.
A steering layer, not a sandbox — pair with agentjail for containment.