CLAUDE.md

1# Caliber
2 
3## What Is This
4 
5`@rely-ai/caliber` — CLI that keeps AI agent configs in sync with your codebase. Generates and refreshes `CLAUDE.md`, `.cursor/rules/`, `AGENTS.md`, `.github/copilot-instructions.md`, and skills across Claude Code, Cursor, Codex, OpenCode, and GitHub Copilot. Supports Anthropic, OpenAI, Google Vertex AI, OpenAI-compatible endpoints, Claude Code CLI, and Cursor ACP.
6 
7## Commands
8 
9```bash
10npm run build        # tsup → dist/
11npm run dev          # watch mode
12npm run test         # vitest run
13npm run lint         # eslint src/
14npx tsc --noEmit     # type check
15npx vitest run src/scoring/__tests__/accuracy.test.ts  # single test
16```
17 
18## Architecture
19 
20**Entry**: `src/bin.ts` → `src/cli.ts` (Commander.js) · **Config**: `tsconfig.json` · `tsup.config.ts` · `vitest.config.ts` · `eslint.config.js` · `.prettierrc`
21 
22**Commands** (`src/commands/`): `init.ts` · `score.ts` · `refresh.ts` · `regenerate.ts` · `config.ts` · `hooks.ts` · `insights.ts` · `learn.ts` · `recommend.ts` · `sources.ts` · `publish.ts` · `undo.ts` · `status.ts` · `bootstrap.ts` · `uninstall.ts` · Helpers: `init-helpers.ts` · `init-prompts.ts` · `init-display.ts` · `setup-files.ts` · `interactive-provider-setup.ts`
23 
24**LLM** (`src/llm/`): `anthropic.ts` · `vertex.ts` · `openai-compat.ts` · `cursor-acp.ts` · `claude-cli.ts` · `types.ts` · `config.ts` · `utils.ts` · `usage.ts` · `model-recovery.ts` · `seat-based-errors.ts` · `index.ts`
25 
26**AI** (`src/ai/`): `generate.ts` · `refine.ts` · `refresh.ts` · `detect.ts` · `learn.ts` · `score-refine.ts` · `prompts.ts` · `stream-parser.ts` · `index.ts`
27 
28**Fingerprint** (`src/fingerprint/`): `index.ts` · `file-tree.ts` · `code-analysis.ts` · `existing-config.ts` · `sources.ts` · `git.ts` · `cache.ts`
29 
30**Scoring** (`src/scoring/`): `index.ts` · `display.ts` · `constants.ts` · `utils.ts` · `history.ts` · `dismissed.ts` · Checks (`src/scoring/checks/`): `existence.ts` · `quality.ts` · `grounding.ts` · `accuracy.ts` · `freshness.ts` · `bonus.ts` · `sources.ts`
31 
32**Writers** (`src/writers/`): `index.ts` · `claude/index.ts` · `cursor/index.ts` · `codex/index.ts` · `opencode/index.ts` · `github-copilot/index.ts` · `refresh.ts` · `staging.ts` · `backup.ts` · `manifest.ts` · `pre-commit-block.ts`
33 
34**Scanner** (`src/scanner/`): `index.ts` — detects local `.mcp.json`, `.cursor/mcp.json` MCP servers, rules, and skills across platforms
35 
36**Lib** (`src/lib/`): `hooks.ts` · `learning-hooks.ts` · `state.ts` · `resolve-caliber.ts` · `builtin-skills.ts` · `sanitize.ts` · `notifications.ts` · `git-diff.ts` · `lock.ts` · `debug-report.ts` · `config-discovery.ts` · `terminal.ts`
37 
38**Utils** (`src/utils/`): `parallel-tasks.ts` · `spinner-messages.ts` · `editor.ts` · `review.ts` · `prompt.ts` · `version-check.ts` · `dependencies.ts` · `waiting-content.ts` · `waiting-cards.json`
39 
40**Telemetry** (`src/telemetry/`): `index.ts` · `config.ts` · `events.ts` · **Learner** (`src/learner/`): `writer.ts` · `storage.ts` · `attribution.ts` · `roi.ts` · `utils.ts` · `stdin.ts`
41 
42**Other**: `github-action/action.yml` · `github-action/index.js` · `assets/video/` (Remotion) · `scripts/` · `docs/FLOW.md` · `src/constants.ts` · `src/test/setup.ts` · `CHANGELOG.md` · `TODOS.md`
43 
44**Workspaces**: `packages/shared/` · `packages/mcp-server/` (MCP server) · `apps/web/` · `apps/api/`
45 
46@./CONTRIBUTING.md
47 
48## Conventions
49 
50- ESM with `.js` import extensions · Tests in `__tests__/` dirs · Setup: `src/test/setup.ts`
51- `unknown` over `any` · Conventional commits (`feat:`, `fix:`, `refactor:`)
52- Dev: `next` branch · Stable: `master` · Node >= 20
53- Config: `~/.caliber/config.json` (mode `0600`) · Constants: `src/constants.ts`
54- `package.json` scripts: `build`, `dev`, `test`, `lint`, `lint:fix`, `format`, `format:check`
55 
56## Key Patterns
57 
58- **Providers**: implement `LLMProvider` from `src/llm/types.ts` (`call()`, `stream()`)
59- **Writers**: `src/writers/claude/index.ts` · `src/writers/cursor/index.ts` · `src/writers/codex/index.ts` · `src/writers/opencode/index.ts` each return `string[]`
60- **Scoring**: checks in `src/scoring/checks/` return `Check[]`, constants in `src/scoring/constants.ts`
61- **No hardcoded mappings**: detection is LLM-driven via `src/ai/detect.ts`
62- `collectFingerprint()` in `src/fingerprint/index.ts` — async with LLM enrichment
63- `resolveCaliber()` from `src/lib/resolve-caliber.ts` for CLI binary resolution
64- Cursor provider: `agent --print --trust --workspace /tmp` in `src/llm/cursor-acp.ts`
65- `getFastModel()` in `src/llm/config.ts`: `ANTHROPIC_SMALL_FAST_MODEL` scoped to anthropic/vertex
66- `validateModel()` skips seat-based providers (`isSeatBased()` in `src/llm/types.ts`)
67- Scoring: deterministic, no LLM · Backups via `src/writers/backup.ts`
68- Scanner: `src/scanner/index.ts` detects local MCP servers, rules, skills for state comparison
69- MCP server workspace: `packages/mcp-server/` · Config discovery: `src/lib/config-discovery.ts`
70- Builtin skills (`src/lib/builtin-skills.ts`): `find-skills`, `save-learning`, `setup-caliber`
71 
72<!-- caliber:managed:pre-commit -->
73## Before Committing
74 
75**IMPORTANT:** Before every git commit, you MUST ensure Caliber syncs agent configs with the latest code changes.
76 
77First, check if the pre-commit hook is already installed:
78```bash
79grep -q &quot;caliber&quot; .git/hooks/pre-commit 2&gt;/dev/null && echo &quot;hook-active&quot; || echo &quot;no-hook&quot;
80```
81 
82- If **hook-active**: the hook handles sync automatically — just commit normally. Tell the user: "Caliber will sync your agent configs automatically via the pre-commit hook."
83- If **no-hook**: run Caliber manually before committing:
84  1. Tell the user: "Caliber: Syncing agent configs with your latest changes..."
85  2. Run: `caliber refresh && git add CLAUDE.md .claude/ .cursor/ .cursorrules .github/copilot-instructions.md .github/instructions/ AGENTS.md CALIBER_LEARNINGS.md .agents/ .opencode/ 2>/dev/null`
86  3. After it completes, briefly tell the user what Caliber updated. Then proceed with the commit.
87 
88If `caliber` is not found, tell the user: "This project uses Caliber for agent config sync. Run /setup-caliber to get set up."
89<!-- /caliber:managed:pre-commit -->
90 
91<!-- caliber:managed:learnings -->
92## Session Learnings
93 
94Read `CALIBER_LEARNINGS.md` for patterns and anti-patterns learned from previous sessions.
95These are auto-extracted from real tool usage — treat them as project-specific rules.
96<!-- /caliber:managed:learnings -->
97 
98<!-- caliber:managed:sync -->
99## Context Sync
100 
101This project uses [Caliber](https://github.com/caliber-ai-org/ai-setup) to keep AI agent configs in sync across Claude Code, Cursor, Copilot, and Codex.
102Configs update automatically before each commit via `caliber refresh`.
103If the pre-commit hook is not set up, run `/setup-caliber` to configure everything automatically.
104<!-- /caliber:managed:sync -->
105