taniwhaai/arai

An instruction file is advice — the model can read CLAUDE.md and still force-push anyway. Arai turns instruction files (CLAUDE.md, AGENTS.md, .cursorrules, and others) into enforcement via native hooks: rules derived from prohibitive language **block the tool call outright**, advisory rules inject the relevant constraint at the point it applies, and a tamper-evident audit log records, per rule, whether the model actually complied.
Quick Start
Arai discovers your instruction files, extracts the rules, classifies their intent, scans your codebase for context, and registers native hooks. In Codex, review and enable the project hooks through /hooks; writing the configuration does not grant host trust. See Codex setup and coverage.
Codex support and the hardening described below require **v1.1.2 or newer** (released 2026-09-16). Every install path below serves it; to build from source instead, run cargo install --path . --locked from this checkout.
To also block violating diffs at git commit (universal across tools that have no PreToolUse hook):
Or add this local pre-commit framework hook. It requires an installed arai with check-diff on PATH; language: system does not install Arai. The repository's own .pre-commit-hooks.yaml manifest exists from v1.1.2 onward.
What It Does
When your AI coding assistant (Claude Code, Grok Build, Codex, or Cursor) is about to do something your rules cover, Arai injects the relevant guardrail — right when it matters. Rules derived from prohibitive predicates (never, forbids, must_not) actually **block the tool call** when the host has enabled the hooks.
Rules only fire when relevant. No noise on ls. No repeating principles already in your instruction files.
Every firing is written to a local audit log, and every PostToolUse is correlated with the matching PreToolUse to produce a **compliance verdict** — so you can measure whether the model actually honours the rules you wrote.
How It Works
1. **Discovers** instruction files in your project and home directory
2. **Extracts** rules by pattern-matching imperative language ("never", "always", "don't", "must")
3. **Classifies** each rule's intent — what action it governs, which tools it applies to, when it should fire
4. **Scans** your codebase with tree-sitter to understand which tools own which directories
5. **Tracks** session state — knows if you've already run tests before pushing
6. **Fires** only relevant rules at the right moment via native hooks (where supported)
Supported Instruction Files
| File | Tool | Enforcement |
|------|------|-------------|
| CLAUDE.md | Claude Code | Hooks (block + advise) |
| .claude/rules/**/*.md | Claude Code | Path-scoped hooks (block + advise) |
| AGENTS.md / Agents.md | Grok Build (native) | Hooks (block; advise best-effort) |
| AGENTS.md / Agents.md | Codex (native) | Hooks (block + advise; requires host trust) |
| ~/.claude/CLAUDE.md | Claude Code (global) | Hooks (block + advise) |
| ~/.grok/ AGENTS.* files | Grok Build (global) | Hooks (block; advise best-effort) |
| .cursorrules / .cursor/rules | Cursor | Hooks (block; advise at session start and after tool calls) |
| .windsurfrules | Windsurf | MCP (advise) |
| .github/copilot-instructions.md | GitHub Copilot | Ingest only |
Rules from every file are parsed, classified, and stored the same way — but
enforcement strength depends on what surface the assistant exposes.
Nested instructions retain directory scope; Claude paths and Cursor globs
restrict file actions. Local scans preserve externally managed policy and prune
only sources they own. Existing stores require explicit adoption of legacy local
sources. See discovery, activation and upgrade handling
and Arai's place upstream of Kete.
On Windows, project state uses the resolved directory path so long names,
8.3 aliases, case variants, and PowerShell hooks share one store. See
Windows state upgrades
if you already have state created under a different path spelling.
- **Claude Code**, **Grok Build**, **Codex**, and **Cursor** support PreToolUse
hooks, so Arai can issue deny decisions and actually block tool calls.