CAI # CAI **Deterministic, zero-token drift detection for AI coding agents — the linter for your AI context.** [![npm version](https://img.shields.io/npm/v/@temroi/cai.svg)](https://www.npmjs.com/package/@temroi/cai) [![CI](https://github.com/t3mr0i/ContextCondense/actions/workflows/ci.yml/badge.svg)](https://github.com/t3mr0i/ContextCondense/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
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 ```bash npm install -g @temroi/cai ``` Or run without global install: ```bash 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](docs/quick-tour.md). Preview what CAI would do: ```bash cai setup --dry-run ``` Create only the `.cai/` scaffold: ```bash cai setup --minimal ``` Full Claude Code setup: ```bash cai setup --claude ``` Useful safer variants: ```bash cai setup --no-hooks cai setup --no-mcp cai setup --no-learn cai setup --cursor cai setup --opencode ``` ## What It Creates Minimal setup creates: ```txt .cai/ ├── AGENTS.md ├── context/ │ ├── architecture.md │ ├── stack.md │ ├── conventions.md │ ├── decisions.md │ └── setup.md └── patterns/ ``` Full setup may also update agent config files: ```txt 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 ` | 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 `): - `rule-globs` — flags `.claude/rules/` / `.cursor/rules/` entries whose `globs:` all match no files Example: ```bash $ 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: ```bash cai verify --skip-adapters ``` Install the Claude Code Stop hook: ```bash 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: ```bash claude mcp add cai -- cai mcp start ``` ## Local Learning CAI can record local prompt corrections and group repeated feedback. Useful commands: ```bash cai learn status cai learn review cai learn write-skill --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: ```bash 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. ```bash 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](https://tauri.app) toolchain): ```bash 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](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 ```bash 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: ```bash 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](LICENSE)