CAI

Verified context quality control for AI coding agents — relevant project constraints, checked and explained.

CAI keeps agent-facing instructions such as CLAUDE.md, AGENTS.md, Cursor rules, and Copilot instructions aligned with the real repository, then serves task-scoped context locally over MCP.

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: cai bench reports a deterministic projection against a named baseline: loading the full scaffold versus an anchor plus routed context. It is useful for local comparison, but it is not a realized saving and does not measure provider cache, cost, or task quality. cai savings --json labels every figure with its baseline and evidence stage.

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

A worked end-to-end example (real failure → diagnosis → fix loop) lives in docs/quick-tour.md.

Preview what CAI would do:

cai setup --dry-run

Create only the .cai/ scaffold:

cai setup --minimal

Minimal setup intentionally stops at installed_unpopulated; file creation is not treated as healthy context. Populate the required .cai/ files, then remove the recorded template guidance and run a current full verification:

cai readiness --finalize --verify

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 readiness [--finalize] [--verify] | Report installed → populated → currently verified state | | 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 readiness, freshness, token budget, and hot files without treating unknown as healthy | | 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 that turns context quality into a guided workflow: set up the scaffold with a local coding agent, prepare the smallest relevant payload for a task, fix drift, and inspect delivery evidence. Today always recommends one next action instead of leaving users in a dashboard.

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.

The task handoff is explicit: “Copy context for agent” puts the exact emitted payload on the clipboard and records a receipt. Automatic delivery happens through the MCP integration; the GUI does not imply that a provider consumed context when it only prepared it locally.

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.

Release

Maintainers cut a release by tagging a commit that has Cai/package.json bumped to the matching version and a Cai/CHANGELOG.md entry:

git tag v4.2.0   # must match package.json version
git push origin v4.2.0

The Release workflow runs typecheck, tests, and build, then publishes @temroi/cai to npm with provenance and creates a GitHub Release from the top entry of Cai/CHANGELOG.md. Requires the NPM_TOKEN secret.

License

MIT