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

curl -sSf https://arai.taniwha.ai/install | sh

cd your-project
arai init

That's it. Arai discovers your instruction files, extracts the rules, classifies their intent, scans your codebase for context, and sets up native hooks so guardrails fire at the right moment.

What It Does

When your AI coding assistant (Claude Code or Grok Build) 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 instead of just advising.

You: "Create a new database migration"

  PreToolUse: Write migrations/versions/001_add_users.py
  → Arai: deny
    reason: "Alembic never: hand-write migration files"
            [from your rules:12, layer-1 imperative]

Assistant: "I should use alembic revision --autogenerate instead..."

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

Rules from every file are parsed, classified, and stored the same way — but enforcement strength depends on what surface the assistant exposes.

• Claude Code and Grok Build both support real PreToolUse hooks, so Arai can issue deny decisions and actually block tool calls.
• On Grok Build, block is load-bearing (decision: deny + exit 2) when the host invokes hooks (verified on 1.0.0 headless with --trust; project hooks stay inactive until the folder is trusted). Advisory text is still emitted as additionalContext on allow responses and recorded in the audit log, but Grok's documented PreToolUse contract only specifies allow / deny+reason — so warn/inform injection into the model is best-effort until the host surfaces that field. Treat block as the guarantee; treat advise as optional context. See docs/upstream/grok-hooks-reverification-1.0.0.md.
• Cursor and Windsurf are MCP clients today — they get strong advisory enforcement via the MCP server.
• GitHub Copilot currently has no live enforcement surface; the file is still ingested for arai stats, arai diff, and the audit log.

Arai hooks several more events alongside the standard tool-call events (when the assistant supports them) so the rule set stays accurate to the live working tree:

• FileChanged + InstructionsLoaded — when an instruction file (CLAUDE.md, rules-dir, memory file, ...) is edited on disk or loaded into context, Arai spawns an arai scan in the background. The next tool-call hook sees the updated guardrails — no manual rescan.
• CwdChanged — when Claude cds into a different directory (monorepo navigation), Arai re-scans rooted at the new directory so the next tool call matches against the right project's rules.
• PostToolBatch — when Claude does a batch of parallel tool calls, Arai correlates each call individually against any PreToolUse firings in the same session, so per-rule compliance verdicts (Obeyed / Ignored / Unclear) stay accurate on parallel workloads.

Smart Matching

Arai doesn't just do keyword matching. It understands your rules:

• Intent classification — "never hand-write migration files" only fires on Write, not Edit (editing existing migrations is fine)
• Code graph — writing to migrations/versions/ triggers alembic rules even if the file doesn't mention alembic, because sibling files import it
• Content sniffing — detects from alembic import op in file content being written
• Session awareness — "never push without running tests" suppresses after tests have been run
• Timing routing — domain rules fire on tool calls, principles stay silent (already in CLAUDE.md)
• Broad imperative coverage — recognises never/always/don't/must, should/shouldn't, cannot/refuse, make sure/be sure, consider/recommend, bare No X prohibitions, conditional shapes (When X, do Y / Before X: do Y / If X → do Y), and the section-aware Use X style-guide pattern. Severity mapping mirrors grammatical weight: should is Inform (soft), should not is Block (the writer chose to call out a specific prohibition).

Why not just an instruction file?

Commands

arai init                  # Discover, extract, classify, scan, set up hooks
arai status                # Show what's being enforced
arai guardrails            # List all active rules
arai why "git push --force" # Explain which rules would fire (dry-run, no audit write)
arai scan                  # Re-scan instruction files
arai scan --code           # Also scan source code (tree-sitter AST)
arai scan --enrich-llm     # Enhance rules via LLM CLI
arai scan --enrich-api     # Enhance rules via API (OpenAI-compatible)
arai add "Never X"         # Add a rule manually
arai audit                 # Inspect the local log of rule firings
arai audit --outcome=ignored # Compliance verdicts where the model ignored a rule
arai audit --rule alembic  # Filter audit by rule subject/predicate/object substring
arai audit --verify        # Verify the SHA-256 hash chain across every day-bucket
arai stats                 # Aggregate audit log — top rules, compliance, token economics
arai stats --by-rule       # Just the per-rule compliance + token economics
arai severity alembic block # Pin a rule's severity (incremental deny rollout)
arai severity --reset alembic # Drop the override; severity reverts to predicate-derived
arai diff CLAUDE.md        # Preview rule-set delta before saving an edit
arai test scenarios.json   # Replay synthetic hook scenarios against rules
arai record --since=1h     # Capture recent firings as a scenario skeleton
arai lint CLAUDE.md        # Parse a file and preview extracted rules
arai trust                 # Manage URLs trusted for shared-policy extends
arai mcp                   # Run the MCP server (stdio) for agent-authored guards
arai upgrade --full        # Switch to full binary (with ONNX enrichment)

Compliance & audit

Beyond firing rules, Arai produces a tamper-evident local record of every guardrail decision and correlates it with what the model actually did. This is what tech leads and compliance reviewers want to see — the trail behind the enforcement.