arai
CLAUDE.md7 starsChanged 6 months agoApache-2.0View on GitHub
Arai is a Rust CLI that enforces AI coding assistant instruction files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) via native hooks (Claude Code, Grok Build, and Codex as of v1.1.2). Current crate version is in Cargo.toml.
- Deletes or force-pushes
- Installs packages
- Commits and pushes
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/claude.mdCLAUDE.md
- compositionSkill
- contract-derivationSkill
- design-docSkill
- dispatcherSkill
- leaf-implementationSkill
- orchestratorSkill
- verifierSkill
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 219
Every firing records which of the seven match_imperative layers produced the rule, plus the source line — exposed via additionalContext, …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md — Arai
Arai is a Rust CLI that enforces AI coding assistant instruction files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) via native hooks (Claude Code, Grok Build, and Codex as of v1.1.2). Current crate version is in Cargo.toml.
Commands
cargo build # Build
cargo test # Run tests
cargo install --path . # Install lean binary
cargo install --path . --features enrich # Install with ONNX enrichment
cargo run -- init # Test init flow (Claude + Grok + Codex hook files)
cargo run -- init --pre-commit # Also install .git/hooks/pre-commit (check-diff --cached)
cargo run -- deinit # Remove Arai hook registrations, leave other handlers
cargo run -- check-diff --cached # Match the staged git diff against guardrails
cargo run -- guardrails # List guardrails
cargo run -- status # Show enforcement status
cargo run -- why "git push --force origin main" # Explain matches (dry-run)
cargo run -- scan --code # Re-scan with AST code graph
cargo run -- scan --enrich-llm # Enrich rules via LLM
cargo run -- add "Never X" # Add a manual rule
cargo run -- audit # Tail the local firing log (today)
cargo run -- audit --json # JSONL stream
cargo run -- audit --verify # Verify SHA-256 hash chain across all day-buckets
cargo run -- audit --event=Compliance # Compliance verdicts (Pre/Post correlation)
cargo run -- audit --outcome=ignored # Rules the model ran despite a Pre-firing
cargo run -- audit --rule alembic # Filter audit by rule subject/predicate/object
cargo run -- audit --verify # Walk hash chain across every day-bucket
cargo run -- audit --ship # Ship pending day-buckets to [ship] url from config
cargo run -- audit --ship https://collector.example.com/arai # One-off collector URL
cargo run -- audit --purge --older=90 --dry-run # Plan a 90-day retention sweep
cargo run -- audit --purge --project=old-proj # Full wipe of one project's audit
cargo run -- stats # Aggregate the audit log (top rules, tools, days, compliance)
cargo run -- stats --by-rule # Just the per-rule compliance ratios
cargo run -- severity # List active severity overrides
cargo run -- severity alembic block # Pin a rule's severity for incremental rollout
cargo run -- severity --reset alembic # Drop the override, fall back to classification
cargo run -- diff CLAUDE.md # Preview rule-set delta vs. live store, no writes
cargo run -- lint CLAUDE.md # Parse a file and preview extracted rules, no DB writes
cargo run -- test scenarios/alembic-migration.json # Replay the canonical scenario
cargo run -- record --since=1h # Build scenarios from recent audit entries
cargo run -- trust --add <url> # Approve a URL for arai:extends
cargo run -- trust --add <url> --bearer-env ARAI_EXTENDS_TOKEN # Private source: send bearer from env var
cargo run -- disable 42 # Silence a rule by triple-id (survives rescan)
cargo run -- enable 42 # Re-enable a previously disabled rule
cargo run -- canonicalize # Extract recognised rules into ./arai.toml
cargo run -- sync # Write arai.toml into existing per-tool instruction files
cargo run -- migrate # Move legacy ~/.arai → ~/.taniwha/arai (prompted, default no)
cargo run -- migrate --yes # Non-interactive migration (for scripts)
cargo run -- mcp # Run the MCP server on stdio (blocks on stdin)
echo '{"tool_name":"Bash","tool_input":{"command":"git push"}}' | cargo run -- guardrails --match-stdin
ARAI_DENY_MODE=off cargo run -- guardrails --match-stdin # Advise-only (no deny)Architecture
src/
├── lib.rs # Library crate root — pub mods for the embeddable core (parser, store, guardrails, hooks, audit, …); CLI-support modules #[doc(hidden)]; telemetry private
├── main.rs # Thin CLI over the library (clap) — arg parsing + IO only
├── config.rs # Config, project paths + slug, env vars, LLM command
├── discovery.rs # Instruction file discovery (scoped / nested; Claude paths, Cursor globs)
├── parser.rs # Rule extraction from markdown (7 layers of pattern matching); tracks layer + expiry
├── store.rs # SQLite + FTS5 (files, triples, code_graph, rule_intent); expired-rule filter
├── guardrails.rs # Term extraction, subject matching, tool scope filtering; format_trace
├── hooks.rs # Hook protocol — PreToolUse/PostToolUse/UserPromptSubmit + FileChanged/InstructionsLoaded/SessionStart auto-rescan; severity → deny/allow; per-host response shapes
├── codex.rs # Codex apply_patch wire format → per-file Write/Edit actions
├── cursor.rs # Cursor Agent hook payloads → canonical envelope; Cursor {"permission"} responses
├── init.rs # `arai init` / `deinit` — discover → extract → classify → scan → hook inject
├── intent.rs # Intent classification — action, timing, tool scope, severity
├── migrate.rs # `arai migrate` — move legacy ~/.arai → ~/.taniwha/arai (prompted)
├── session.rs # Session state — prerequisite tracking across tool calls
├── code_scanner.rs # tree-sitter AST parsing — import extraction for 7 languages
├── enrich.rs # Tier 2 (ONNX sentence transformer) + Tier 3 (LLM shell-out / API)
├── audit.rs # Local JSONL firing log — record_firing, record_event, layer_label
├── compliance.rs # Pre/Post correlation — Obeyed/Ignored/Unclear verdicts per rule
├── stats.rs # Aggregate views — `arai stats`, per-rule compliance, token economics
├── scenarios.rs # Scenario replay harness — `arai test <file>`
├── repo_check.rs # Repo-layer matcher — git diffs synthesised as Write/Edit
├── canonicalize.rs # `arai canonicalize` — instruction files → arai.toml
├── sync.rs # `arai sync` — arai.toml → existing per-tool instruction files
├── ship.rs # `arai audit --ship`
├── source_scope.rs # Directory / path / glob scope for nested instruction files
├── style.rs # Colour / glyph helpers for CLI output
├── extends.rs # `arai:extends` upstream-policy fetch + trust list
├── mcp.rs # Stdio MCP — add_guard, list_guards, check_action, recent_decisions
├── telemetry.rs # Anonymous usage analytics (opt-out, no project context)
├── prompt_collector.rs # Pure prompt-pattern collector — regex seed ruleset, PromptMatchReceipt; no enforcement
├── upgrade.rs # Self-upgrade between lean/full binaries
└── codex.rs # Codex apply_patch / payload normalization (internal)Prompt-collector module (src/prompt_collector.rs)
prompt_collector is a pure computation module that tests a set of labelled regex patterns against a user prompt and returns PromptMatchReceipt values — one per matched rule. It carries a compiled-in seed ruleset (starter labels: deploy, production, secret, password, kubectl apply, force push) that represent observation points, not policy decisions; operators should tune this list for their context. The UserPromptSubmit hook handler calls collect_prompt_matches with the seed ruleset and writes each receipt to the local audit log via record_event, so matches are visible under arai audit --event=PromptMatch. The module performs no enforcement (no block, no warn, no response mutation) and makes no network calls; it is within the kete charter boundary for local-only, read-only observation of prompt content.
Extending the match pipeline
hooks::match_hook(hook, cfg, db) is the single pure entry point used
by both the live stdio handler and the arai test scenario runner.
Any change to rule-matching logic goes there so the two paths stay
identical. Side effects (audit write, telemetry, session write) live
only on the handle_stdin path.
Two layers of observability
telemetry.rs— anonymous usage. Tracks aggregate counters ("a rule fired on some Bash call") so we can tell whether guardrails are useful at all. No project paths, no rule text, no code content. Opt-out viaARAI_TELEMETRY=offorDO_NOT_TRACK=1.audit.rs— local inspection. Per-project JSONL of every firing, with full rule + tool + prompt-preview context. Stays on the user's machine. Surfaced viaarai audit.
They are intentionally separate paths: turning off telemetry does not disable the local audit log, and nothing in the local audit log ever leaves the machine.
Key Design Constraints
- Zero noise — only fire domain-specific guardrails, never repeat CLAUDE.md content
- Domain rules only — rules must reference a known tool to fire on tool calls
- Session-aware — tracks prerequisites (e.g., "cargo test" before "git push")
- Three enrichment tiers — taxonomy (free) → ONNX model (local) → LLM (any provider)
- Timing-aware — rules route to the right hook event (PreToolUse vs UserPromptSubmit)
- Severity-aware — prohibitive predicates block, affirmative predicates warn, prefers informs
- ~22 ms skip-tool fast-exit, ~32 ms full match (median) — see
bench/hot_path.shfor the breakdown; cost is dominated by binary fork+exec, not matching - Single binary — no runtime dependencies for users
Historical notes below (v0.2.x) are kept for parser/compliance archaeology. Current release is v1.1.2 (Codex hooks, scoped discovery, check-diff).
v0.2.11 additions at a glance
- Twelve new parser patterns (
parser::match_imperative) shipped together so users who write rules in any of these styles get them honoured rather than silently dropped. Severity mapping mirrors grammatical weight (shouldis softer thanmust, so it routes toprefers/Inform;should notis an explicit prohibition so it routes tomust_not/Block). - New Layer 7 (
conditional imperative) — catches the trigger- paired-with-imperative shape that previously slipped past every layer ("When working in parallel, run tests in isolation"). - Layer 5 section-context gate —
^use\s+now also fires when the section header matchesConventions / Rules / Style / Guidelines / Best Practices / ..., capturing the style-guide pattern where the framing makes the imperative explicit. - Bold-label discriminator (
is_bold_label) — `No build process- this is a zero-build extension.
is feature-absence DESCRIPTION, not a rule; the guard prevents^noand^considerfrom over-extracting on labelled list items, while still lettingAlways run tests` (bold emphasis on a Layer 1 leader) extract normally.
- this is a zero-build extension.
- Coverage corpus + integration test —
tests/parser_coverage/ships a synthetic CLAUDE.md exercising every pattern with positive AND negative cases, plus atests/parser_coverage.rsintegration test that drives the livearai lint --jsonbinary. Locks the expected behaviour so future parser changes can't silently regress on the most-common shapes.
v0.2.9 additions at a glance
- Per-session repeat-injection suppression (
session::partition_ seen_rules,session::mark_rules_seen). When the same rule fires a second time in a session the hook emits a compact one-liner (- still: subject predicate object) instead of re-injecting the full source/layer/severity payload. Saves ~50 tokens per re-fire and reduces attention dilution. State lives in the existing per-session JSON pattern, capped at 500 ids. Mark-as-seen happens after the audit write so a panic between match and write can't permanently suppress a rule the model never saw. seen_beforeper-rule audit field. Additive boolean on every entry inrules[]; older lines are read asfalse. Letsarai statscount suppression events post-hoc without holding any session state of its own.- Token-economics section in
arai stats(stats::TokenEconomics). Three streams: repeat-injection suppressions (~50 ea.), denied- and-honored mistakes (obeyed+blockseverity, ~2000 ea.), advised-and-honored events (~500 ea.). Calibration constants documented insrc/stats.rsso they move atomically. Output is labelled "estimates, not measurements" everywhere — over-claiming here is the easy mistake to make. Suppressed entirely when no streams have data, so first-run users don't see a "0 saved" line.arai stats --jsonexposes atoken_economicsobject.
v0.2.6 additions at a glance
- Per-rule compliance roll-up in
arai stats— joins Pre firings and Compliance verdicts viatriple_idto producefires/obeyed/ignored/unclear/ratioper rule.--by-ruleshows only that section. The maintainer's "is this rule actually working?" question, answered from data Arai already collects. (v0.2.7: dedupe per Pre — first-definitive-wins so unrelated Posts don't inflate the denominator.) - Per-rule severity override (
arai severity). Stored in a newrule_intent.severity_overridecolumn thatclassify_all_guardrailsdoesn't touch on re-scan, so manual rollout decisions survive.get_rule_intentreturns the override when set; falls back to the classified severity otherwise. arai_recent_decisionsMCP tool. Mirror of the maintainer- side audit feed, exposed to the agent so it can self-check after a deny without parsing the on-screen reason or re-trying the same thing twice. StripsComplianceevents (verdicts, not decisions).arai audit --rule <pattern>filter. Substring match against rule subject/predicate/object across both top-level firings and Compliancepayload.rules[]. Pairs with--outcome=ignored.arai diff <file>. Preview rule-set delta against the live store before saving an instruction-file edit; emits added / removed / moved (line number changed for an unchanged SPO). Pre-commit-hook fodder via--json.
v0.2.3 additions at a glance
- Severity + deny mode (
intent::Severity).never/forbids/must_not→Block→permissionDecision: "deny"on PreToolUse.ARAI_DENY_MODE=offforces advise-only for incremental rollout. - Rule derivation trace (
parser::Triple::layer,Guardrail::layer,Guardrail::line_start,audit::layer_label). Every firing records which of the sevenmatch_imperativelayers produced the rule, plus the source line — exposed viaadditionalContext, the audit JSON, andarai why. - Compliance tracking (
compliance.rs). On PostToolUse, correlate against recent PreToolUse firings and emit aComplianceaudit event with anObeyed | Ignored | Unclearverdict per rule. CLI filter:arai audit --outcome=ignored. - Rule expiry (
parser::Triple::expires_at,parser::extract_expiry). Trailing(expires YYYY-MM-DD)or(until YYYY-MM-DD)annotation parses into a date; SQL filter drops expired rules on load. arai why(inmain.rs). Read-only dry-run through the livematch_hookpipeline. Shows matched rules, severity, layer, source, line, and match-percentage.
rustc 1.95 caveat
The dead-code liveness pass in rustc 1.95 ICEs on certain pub fn
shapes declared inside parser.rs (specifically a match-returning-
&'static str with escaped quote strings). If you add a new helper in
parser.rs and cargo check panics with
#0 [check_mod_deathness] checking deathness of variables in module 'parser',
move the helper to audit.rs or another module. audit::layer_label
was moved for this reason.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

