CAI

Deterministic, zero-token drift detection for AI coding agents — the linter for your AI context.

CAI keeps agent-facing instructions such as CLAUDE.md, AGENTS.md, Cursor rules, and Copilot instructions aligned with the real repository.

It is a CLI for:

• detecting drift between docs and code, deterministically — no AI, no network
• failing CI when the scaffold no longer matches the code (cai check --min-score)
• generating a small .cai/ project scaffold for agents
• serving task-scoped project context to agents over MCP
• tracking local recurring corrections and reusable task patterns

CAI runs locally. Drift checks do not upload source code and do not call an AI model.

On tokens: routing task-scoped context instead of loading every doc cuts standing per-turn context. Measure it on your own repo with cai bench — it reports a real number (and the always-loaded anchor cost), not a marketing multiplier. On CAI's own scaffold that is a 58.6% median per-turn saving (14 files, 12.8k → ~5.3k tokens, 1.3k anchor tax); savings scale with scaffold size, and on a small project they may be near zero.

Install

npm install -g @temroi/cai

Or run without global install:

npx @temroi/cai doctor --no-scaffold

Requires Node.js 20 or newer.

Quick Start

Preview what CAI would do:

cai setup --dry-run

Create only the .cai/ scaffold:

cai setup --minimal

Full Claude Code setup:

cai setup --claude

Useful safer variants:

cai setup --no-hooks
cai setup --no-mcp
cai setup --no-learn
cai setup --cursor
cai setup --opencode

What It Creates

Minimal setup creates:

.cai/
├── AGENTS.md
├── context/
│   ├── architecture.md
│   ├── stack.md
│   ├── conventions.md
│   ├── decisions.md
│   └── setup.md
└── patterns/

Full setup may also update agent config files:

CLAUDE.md
.claude/settings.json
.claude/rules/
.claude/skills/
.cursorrules
.github/copilot-instructions.md

Run cai setup --dry-run before setup if you want to see the exact writes first.

Core Commands

| Command | Purpose | |---|---| | cai doctor --no-scaffold | Read-only project diagnosis before setup | | cai setup --dry-run | Preview setup changes | | cai setup --minimal | Create only .cai/ | | cai setup --claude | Setup with Claude Code integration | | cai check | Detect drift between scaffold and repo | | cai check --quiet | CI-friendly drift check | | cai fix | Deterministic scaffold repairs | | cai sync | Generate targeted AI prompts for doc updates | | cai verify | Run typecheck, build, detected adapters, and drift | | cai health | Show score, freshness, token budget, and hot files | | cai stats | Show local MCP query telemetry | | cai learn review | Review recurring local prompt corrections | | cai learn write-skill <id> | Save a recurring correction as provider-targeted SKILL.md files | | cai learn disable | Stop correction recording | | cai learn forget | Delete recorded corrections | | cai pattern suggest | Suggest reusable task patterns | | cai pattern recurring | Find repeated task types from git history | | cai update | Update CAI scaffold without overwriting your content |

Drift Detection

cai check compares agent instructions with repository reality.

It checks things like:

• file paths that no longer exist
• npm scripts or commands that were renamed
• dependencies mentioned in docs but missing from manifests
• documented env vars missing from examples
• stale scaffold files
• workspace dependency mismatches
• tool config files that drifted apart
• broken intra-repo markdown links and heading anchors

Opt-in checks (run with cai check --only <name>):

• rule-globs — flags .claude/rules/ / .cursor/rules/ entries whose globs: all match no files

Example:

$ cai check
Score: 84/100

error   command    npm run test:unit is not defined in package.json
warning path       docs mention src/server.ts, but the file is missing

cai fix handles deterministic repairs. cai sync creates targeted update prompts for changes that need review.

Verification

cai verify is meant for agent back-pressure: run cheap checks before the agent says the task is done.

It auto-detects what applies:

• TypeScript: npm run typecheck, npm run type-check, or npx tsc --noEmit
• Node: npm run build, npm run lint, optional npm run react-doctor
• Python: ruff and mypy when configured
• Go: go test ./...
• Rust: cargo check
• Java: Maven or Gradle compile
• Ruby: bundle exec rubocop
• CAI drift: cai check --skip staleness

Skip adapters if you only want the core CAI checks:

cai verify --skip-adapters

Install the Claude Code Stop hook:

cai verify-install-hook

MCP Context

CAI can register an MCP server so agents can query focused context instead of loading a large instruction file every time.

Available context includes:

• project setup and architecture notes
• stack and dependency information
• conventions and decisions
• pattern suggestions
• drift status
• workspace and command maps

Manual registration:

claude mcp add cai -- cai mcp start

Local Learning

CAI can record local prompt corrections and group repeated feedback.

Useful commands:

cai learn status
cai learn review
cai learn write-skill <id> --provider all
cai learn disable
cai learn forget

This is local rule discovery. It is not model training. Skill export keeps a canonical .cai/skills/ copy and can mirror to Claude Code or Codex skill directories.

Security

CAI reads local manifests, scaffold files, agent instruction files, and selected git history.

CAI writes only local project or user files such as:

• .cai/
• .cai/.cache/
• configured agent instruction files
• optional Claude Code hook and MCP config

CAI drift checks:

• do not upload source code
• do not call AI models
• do not require an account

Some commands intentionally execute local project tools, especially cai verify, hooks, and setup helpers. Use cai setup --dry-run, cai setup --minimal, --no-hooks, --no-mcp, and --no-learn when you want a narrower install.

Set this to disable local MCP query telemetry and drift history:

CAI_NO_TELEMETRY=1

Desktop Sidecar (GUI)

CAI ships an optional desktop sidecar — a glanceable drift dashboard with a mood-driven mascot, per-file finding cards, and approve-before-apply fixes. It is the visual counterpart to cai health: same data, ambient surface.

cai gui

The GUI is a separate Tauri app (Rust shell + system webview) that lives in the gui/ workspace. It is not part of the npm package — the CLI stays dependency-light. cai gui only locates and launches the installed binary; it carries no GUI code itself.

Build the GUI (requires the Rust + Tauri toolchain):

cd gui
npm install
npm run build      # produces gui/src-tauri/target/release/cai-gui

cai gui resolves the binary from the build output or from CAI_GUI_BIN. The GUI shells out to cai check --json and cai sync — the CLI remains the single source of drift truth. See docs/gui.md for the contract, distribution, and signing notes.

Supported Project Types

CAI can inspect common manifests:

• package.json
• pyproject.toml
• requirements.txt
• go.mod
• Cargo.toml
• pom.xml
• build.gradle
• build.gradle.kts
• Gemfile

Updating

npm update -g @temroi/cai
cai update

context/, patterns/, and your project notes are kept.

License

MIT