What is bestAI?

AI agents ignore CLAUDE.md rules 94% of the time in production. bestAI fixes this with deterministic enforcement hooks — Bash scripts that intercept tool calls and block violations with exit 2. No amount of prompt engineering can bypass a hook.

Built on evidence from the Nuconic case study: 234 sessions, 16,761 tool calls, 29 days of production data.

Quick Start

# Install globally
npm install -g @radekzm/bestai

# Initialize in your project
cd your-project
bestai init .

# Verify installation
bestai doctor

Or without global install:

npx @radekzm/bestai@latest init /path/to/your/project
npx @radekzm/bestai@latest doctor /path/to/your/project

How It Works

graph LR
    User[User Prompt] --> Hook{bestAI Hooks}
    Hook -- Block --> Fix[Auto-Fix Suggestion]
    Hook -- Allow --> Exec[Agent Execution]
    Exec --> GPS[Sync GPS State]
    GPS --> Context[Update Context Tiers]
    Context --> User

CLAUDE.md = guidance   (advisory — 6% compliance in production)
Hooks     = enforcement (deterministic — exit 2 blocks the action)

Critical rules go in hooks. Style preferences stay in CLAUDE.md.

Core Mechanisms

1. Deterministic Force-Field (Fail-Closed Hooks)

Every file write or shell command is intercepted. If an agent tries to edit a frozen file, the hook returns exit 2 — action blocked. Edit/Write hooks are deterministic (exact path match, cannot be bypassed). Bash hooks are best-effort (~95% enforcement via pattern matching).

2. 5-Tier Context OS

Bypasses token limits by segmenting memory into tiers:

• T0 — Hot context (GPS, active task)
• T1 — Session state (facts, proofs, blockers)
• T2 — Memory (weighted entries with generational GC)
• T3 — Summaries (hierarchical, built offline)
• T4 — Frozen config (templates, rules)

3. Circuit Breaker

Two-phase pattern from distributed systems. circuit-breaker.sh (PostToolUse) tracks consecutive failures. After N failures → OPEN. circuit-breaker-gate.sh (PreToolUse) blocks commands while circuit is open. Supports HALF-OPEN auto-transition after cooldown.

4. Smart Context

Two implementations (mutually exclusive):

• v1 (preprocess-prompt.sh) — keyword/trigram matching. Fast (~200ms). No API calls.
• v2 (smart-preprocess-v2.sh) — LLM-scored injection via Haiku. Slower (~500ms), more accurate for ambiguous queries.

5. Session Persistence

At session end: sync-state.sh persists TOP-10 FACTS, TOP-5 PROOFS, TOP-3 BLOCKERS, LAST SESSION DELTA. At session start: rehydrate.sh restores state — zero file globs, paths from memory.

6. Memory GC

memory-compiler.sh implements generational garbage collection. Entries scored by relevance × recency × usage_count. Three generations: hot → warm → cold → purged.

Hook Reference

All hooks live in hooks/ and are declared in hooks/manifest.json with priority, latency budget, and dependency graph.

PreToolUse

PostToolUse

UserPromptSubmit

SessionStart / Stop

Toolbelt

Evidence

Based on the Nuconic case study: 234 sessions, 16,761 tool calls, 29 days of production data.

Key finding: CLAUDE.md-only compliance was 6%. With deterministic hooks: 100% for Edit/Write, ~95% for Bash (pattern matching limitation).

Maturity Matrix

Learn More

• QUICKSTART.md — 2-minute setup guide
• AGENTS.md — Full hook reference for AI agents
• Architecture — Technical internals
• Troubleshooting — Problem → solution guide
• Modules — Detailed guidelines (01-core, 02-operations, 03-advanced)