@rely-ai/caliber 1.18.8 → 1.18.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +115 -148
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -14,45 +14,24 @@
14
14
 
15
15
  ---
16
16
 
17
- Caliber scans your project — languages, frameworks, dependencies, file structure — and generates tailored config files for **Claude Code**, **Cursor**, and **OpenAI Codex**. If configs already exist, it audits them against your actual codebase and suggests targeted improvements.
18
-
19
- 🔑 **API Key Optional** — use your existing Claude Code or Cursor subscription. Or bring your own key (Anthropic, OpenAI, Vertex AI, any OpenAI-compatible endpoint).
20
-
21
- 🧠 **BYOAI** — Caliber works where you do. All LLM processing runs through your own models — no data is sent to third parties.
22
-
23
- ### Why Caliber?
24
-
25
- Caliber **generates, audits, and maintains** your agentic development sessions.
26
-
27
- - 🏗️ **Generates, not just score** — builds your CLAUDE.md, Cursor rules, AGENTS.md, skills, and MCP configs from scratch
28
- - 🔀 **Multi-agent** — one command sets up Claude Code, Cursor, and Codex together
29
- - 🌍 **Any codebase** — TypeScript, Python, Go, Rust, Terraform, Java, Ruby — detection is fully LLM-driven, not hardcoded
30
- - 🧩 **Finds and installs skills** — searches community registries and installs relevant skills for your stack
31
- - 🔗 **Discovers MCP servers** — auto-detects tools your project uses and installs matching MCP servers
32
- - 🔄 **Keeps configs fresh** — git hooks and session hooks auto-update your docs as your code changes
33
- - ↩️ **Fully reversible** — automatic backups, score regression guard, and one-command undo
34
-
35
- ## 🚀 Quick Start
36
-
37
- ```bash
38
- npx @rely-ai/caliber init
39
- ```
40
-
41
- That's it. On first run, Caliber walks you through provider setup interactively.
42
-
43
- Or install globally:
17
+ Caliber analyzes your codebase — languages, frameworks, dependencies, architecture — and generates tailored, high-quality configs for **Claude Code**, **Cursor**, and **OpenAI Codex**. If configs already exist, it scores them, fixes what's stale, and keeps everything in sync as your code evolves.
44
18
 
45
19
  ```bash
46
20
  npm install -g @rely-ai/caliber
47
21
  caliber init
48
22
  ```
49
23
 
50
- > **Already have an API key?** Skip the interactive setup:
51
- >
52
- > ```bash
53
- > export ANTHROPIC_API_KEY=sk-ant-...
54
- > npx @rely-ai/caliber init
55
- > ```
24
+ No API key required — works with your existing **Claude Code** or **Cursor** subscription. Or bring your own key (Anthropic, OpenAI, Vertex AI, any OpenAI-compatible endpoint).
25
+
26
+ ## 💡 What Caliber Does
27
+
28
+ | Without Caliber | With Caliber |
29
+ |---|---|
30
+ | Hand-write CLAUDE.md, Cursor rules, AGENTS.md separately | One command generates all three, tuned to your actual codebase |
31
+ | Configs reference files that no longer exist | Deterministic scoring catches stale references and drift |
32
+ | New team members start with no AI context | `caliber init` gives any contributor a complete setup in seconds |
33
+ | Configs diverge across AI tools | Cross-platform parity — Claude, Cursor, and Codex stay consistent |
34
+ | No idea if your config is actually helping | Score your setup (A–F grade) and see exactly what to improve |
56
35
 
57
36
  ## ⚙️ How It Works
58
37
 
@@ -62,93 +41,63 @@ caliber init
62
41
  ├─ 1. 🔌 Connect Choose your LLM provider — Claude Code seat, Cursor seat,
63
42
  │ or an API key (Anthropic, OpenAI, Vertex AI)
64
43
  │
65
- ├─ 2. 🔍 Discover Analyze languages, frameworks, dependencies, file structure,
66
- │ and existing agent configs via LLM
44
+ ├─ 2. 🔍 Discover Fingerprint your project: languages, frameworks, dependencies,
45
+ │ file structure, and existing agent configs
67
46
  │
68
- ├─ 3. 🛠️ Generate Create CLAUDE.md + skills in parallel (core docs via smart
69
- │ model, skills via fast model). Auto-polishes for max score
47
+ ├─ 3. 🛠️ Generate Build optimized configs with parallel LLM calls
48
+ │ (heavy model for docs, fast model for skills)
70
49
  │
71
- ├─ 4. 👀 Review See a diff of proposed changes — accept, refine via
72
- │ chat, or decline. All changes are backed up automatically
50
+ ├─ 4. 👀 Review See a diff of every proposed change — accept, refine
51
+ │ via chat, or decline. All originals are backed up
73
52
  │
74
- └─ 5. 🧩 Skills Search community skill registries and install relevant
53
+ └─ 5. 🧩 Skills Search community registries and install relevant
75
54
  skills for your tech stack
76
55
  ```
77
56
 
78
- Caliber works on **any codebase** — TypeScript, Python, Go, Rust, Terraform, Java, Ruby, and more. Language and framework detection is fully LLM-driven, not hardcoded.
57
+ Already have a setup? If your existing config scores **95+**, Caliber skips full regeneration and applies targeted fixes to the specific checks that are failing.
79
58
 
80
59
  ### 📦 What It Generates
81
60
 
82
- | File | Platform | Purpose |
83
- | --------------------------- | ----------- | ------------------------------------------------------------------- |
84
- | `CLAUDE.md` | Claude Code | Project context — build/test commands, architecture, conventions |
85
- | `.cursor/rules/*.mdc` | Cursor | Modern rules with frontmatter (description, globs, alwaysApply) |
86
- | `.cursorrules` | Cursor | Legacy rules file (if no `.cursor/rules/` exists) |
87
- | `AGENTS.md` | Codex | Project context for OpenAI Codex |
88
- | `.claude/skills/*/SKILL.md` | Claude Code | Reusable skill files following [OpenSkills](https://agentskills.io) |
89
- | `.cursor/skills/*/SKILL.md` | Cursor | Skills for Cursor |
90
- | `.agents/skills/*/SKILL.md` | Codex | Skills for Codex |
91
- | `.mcp.json` | Claude Code | MCP server configurations |
92
- | `.cursor/mcp.json` | Cursor | MCP server configurations |
93
- | `.claude/settings.json` | Claude Code | Permissions and hooks |
61
+ **Claude Code**
62
+ - `CLAUDE.md` — Project context, build/test commands, architecture, conventions
63
+ - `.claude/skills/*/SKILL.md` — Reusable skills ([OpenSkills](https://agentskills.io) format)
64
+ - `.mcp.json` — Auto-discovered MCP server configurations
65
+ - `.claude/settings.json` — Permissions and hooks
94
66
 
95
- If these files already exist, Caliber audits them and suggests improvements — keeping what works, fixing what's stale, adding what's missing.
67
+ **Cursor**
68
+ - `.cursor/rules/*.mdc` — Modern rules with frontmatter (description, globs, alwaysApply)
69
+ - `.cursor/skills/*/SKILL.md` — Skills for Cursor
70
+ - `.cursor/mcp.json` — MCP server configurations
96
71
 
97
- ### 🛡️ Safety
72
+ **OpenAI Codex**
73
+ - `AGENTS.md` — Project context for Codex
74
+ - `.agents/skills/*/SKILL.md` — Skills for Codex
98
75
 
99
- Every change Caliber makes is reversible:
100
-
101
- - 💾 **Automatic backups** — previous versions saved to `.caliber/backups/{timestamp}/` before every write
102
- - 📊 **Score regression guard** — if a regeneration produces a lower score, changes are auto-reverted
103
- - ↩️ **Full undo** — `caliber undo` reverts all changes made by Caliber
104
- - 🔍 **Dry run** — preview any command's changes with `--dry-run`
105
-
106
- ## 📋 Commands
76
+ If these files already exist, Caliber audits them and suggests improvements — keeping what works, fixing what's stale, adding what's missing.
107
77
 
108
- | Command | Description |
109
- | -------------------- | ---------------------------------------------------- |
110
- | `caliber init` | 🏁 Initialize your project — full 5-step wizard |
111
- | `caliber score` | 📊 Score your config quality (deterministic, no LLM) |
112
- | `caliber skills` | 🧩 Discover and install community skills |
113
- | `caliber regenerate` | 🔄 Re-analyze and regenerate your setup |
114
- | `caliber refresh` | 🔃 Update docs based on recent code changes |
115
- | `caliber hooks` | 🪝 Manage auto-refresh hooks |
116
- | `caliber config` | ⚙️ Configure LLM provider, API key, and model |
117
- | `caliber status` | 📌 Show current setup status |
118
- | `caliber undo` | ↩️ Revert all changes made by Caliber |
78
+ ## ✨ Key Features
119
79
 
120
- ### Examples
80
+ ### 🌍 Any Codebase
81
+ TypeScript, Python, Go, Rust, Java, Ruby, Terraform, and more. Language and framework detection is fully LLM-driven — no hardcoded mappings. Caliber works on any project.
121
82
 
83
+ ### 🔀 Any AI Tool
84
+ Target a single platform or all three at once:
122
85
  ```bash
123
- # Initialize
124
- caliber init # Interactive — picks agent, walks through setup
125
- caliber init --agent claude # Target Claude Code only
126
- caliber init --agent cursor # Target Cursor only
127
- caliber init --agent codex # Target OpenAI Codex only
128
- caliber init --agent all # Target all three
86
+ caliber init --agent claude # Claude Code only
87
+ caliber init --agent cursor # Cursor only
88
+ caliber init --agent codex # Codex only
89
+ caliber init --agent all # All three
129
90
  caliber init --agent claude,cursor # Comma-separated
130
- caliber init --dry-run # Preview without writing files
131
- caliber init --force # Overwrite existing setup without prompting
132
-
133
- # Scoring
134
- caliber score # Full breakdown with grade (A-F)
135
- caliber score --json # Machine-readable output
136
- caliber score --agent claude # Score for a specific agent
137
-
138
- # Day-to-day
139
- caliber regenerate # Re-analyze and regenerate (alias: regen, re)
140
- caliber refresh # Update docs from recent git changes
141
- caliber refresh --dry-run # Preview what would change
142
- caliber skills # Browse and install community skills
143
- caliber hooks # Toggle auto-refresh hooks
144
- caliber hooks --install # Enable all hooks non-interactively
145
- caliber status # Show what Caliber has set up
146
- caliber undo # Revert everything
147
91
  ```
148
92
 
149
- ## 📊 Scoring
93
+ ### 💬 Chat-Based Refinement
94
+ Not happy with the generated output? During review, refine via natural language — describe what you want changed and Caliber iterates until you're satisfied.
150
95
 
151
- `caliber score` gives you a deterministic, tech-stack-agnostic quality score. No LLM needed — it cross-references your config files against the actual project filesystem.
96
+ ### 🔗 MCP Server Discovery
97
+ Caliber detects the tools your project uses (databases, APIs, services) and auto-configures matching MCP servers for Claude Code and Cursor.
98
+
99
+ ### 📊 Deterministic Scoring
100
+ `caliber score` evaluates your config quality without any LLM calls — purely by cross-referencing config files against your actual project filesystem.
152
101
 
153
102
  ```
154
103
  Agent Config Score 88 / 100 Grade A
@@ -161,59 +110,76 @@ caliber undo # Revert everything
161
110
  BONUS 5 / 5
162
111
  ```
163
112
 
164
- | Category | Points | What it checks |
165
- | ---------------------- | ------ | ------------------------------------------------------------------ |
166
- | **Files & Setup** | 25 | Config files exist, skills present, MCP servers, cross-platform parity |
167
- | **Quality** | 25 | Has code blocks, concise token budget, concrete instructions, structured headings |
168
- | **Grounding** | 20 | Config references actual project directories and files |
169
- | **Accuracy** | 15 | Referenced paths exist on disk, config is in sync with code (git-based) |
170
- | **Freshness & Safety** | 10 | Recently updated, no leaked secrets, permissions configured |
171
- | **Bonus** | 5 | Auto-refresh hooks, AGENTS.md, OpenSkills format |
172
-
173
- Every failing check includes structured fix data — when `caliber init` runs, the LLM receives exactly what's wrong and how to fix it.
174
-
175
- ## 🧩 Skills
176
-
177
- Caliber searches three community registries and scores results against your project
178
-
179
- ```bash
180
- caliber skills
181
- ```
113
+ <details>
114
+ <summary>Scoring breakdown</summary>
182
115
 
183
- Skills are scored by LLM relevance (0–100) based on your project's actual tech stack and development patterns, then you pick which ones to install via an interactive selector. Installed skills follow the [OpenSkills](https://agentskills.io) standard with YAML frontmatter.
116
+ | Category | Points | What it checks |
117
+ |---|---|---|
118
+ | **Files & Setup** | 25 | Config files exist, skills present, MCP servers, cross-platform parity |
119
+ | **Quality** | 25 | Code blocks, concise token budget, concrete instructions, structured headings |
120
+ | **Grounding** | 20 | Config references actual project directories and files |
121
+ | **Accuracy** | 15 | Referenced paths exist on disk, config freshness vs. git history |
122
+ | **Freshness & Safety** | 10 | Recently updated, no leaked secrets, permissions configured |
123
+ | **Bonus** | 5 | Auto-refresh hooks, AGENTS.md, OpenSkills format |
184
124
 
185
- ## 🔄 Auto-Refresh
125
+ Every failing check includes structured fix data — when `caliber init` runs, the LLM receives exactly what's wrong and how to fix it.
186
126
 
187
- Keep your agent configs in sync with your codebase automatically:
127
+ </details>
188
128
 
189
- | Hook | Trigger | What it does |
190
- | --------------------- | ------------------- | --------------------------------------- |
191
- | 🤖 **Claude Code** | End of each session | Runs `caliber refresh` and updates docs |
192
- | 📝 **Git pre-commit** | Before each commit | Refreshes docs and stages updated files |
129
+ ### 🔄 Auto-Refresh
130
+ Keep configs in sync with your codebase automatically:
193
131
 
194
- Set up hooks interactively with `caliber hooks`, or non-interactively:
132
+ | Hook | Trigger | What it does |
133
+ |---|---|---|
134
+ | **Claude Code** | End of each session | Runs `caliber refresh` and updates docs |
135
+ | **Git pre-commit** | Before each commit | Refreshes docs and stages updated files |
195
136
 
196
137
  ```bash
197
138
  caliber hooks --install # Enable all hooks
198
139
  caliber hooks --remove # Disable all hooks
199
140
  ```
200
141
 
201
- The refresh command analyzes your git diff (committed, staged, and unstaged changes) and updates your config files to reflect what changed. It works across multiple repos if run from a parent directory.
142
+ The `refresh` command analyzes your git diff (committed, staged, and unstaged changes) and updates config files to reflect what changed. Works across multiple repos when run from a parent directory.
143
+
144
+ ### 🛡️ Fully Reversible
145
+ Every change Caliber makes can be undone:
146
+ - **Automatic backups** — originals saved to `.caliber/backups/` before every write
147
+ - **Score regression guard** — if a regeneration produces a lower score, changes are auto-reverted
148
+ - **Full undo** — `caliber undo` restores everything to its previous state
149
+ - **Dry run** — preview changes with `--dry-run` before applying
150
+
151
+ ## 📋 Commands
152
+
153
+ | Command | Description |
154
+ |---|---|
155
+ | `caliber init` | Full setup wizard — analyze, generate, review, install skills |
156
+ | `caliber score` | Score config quality (deterministic, no LLM) |
157
+ | `caliber regenerate` | Re-analyze and regenerate configs (aliases: `regen`, `re`) |
158
+ | `caliber refresh` | Update docs based on recent code changes |
159
+ | `caliber skills` | Discover and install community skills |
160
+ | `caliber hooks` | Manage auto-refresh hooks |
161
+ | `caliber config` | Configure LLM provider, API key, and model |
162
+ | `caliber status` | Show current setup status |
163
+ | `caliber undo` | Revert all changes made by Caliber |
202
164
 
203
165
  ## 🔌 LLM Providers
204
166
 
205
- | Provider | Setup | Default Model |
206
- | ------------------------------ | ------------------------------------- | -------------------------- |
207
- | 🟣 **Claude Code** (your seat) | `caliber config` → Claude Code | Inherited from Claude Code |
208
- | 🔵 **Cursor** (your seat) | `caliber config` → Cursor | Inherited from Cursor |
209
- | 🟠 **Anthropic** | `export ANTHROPIC_API_KEY=sk-ant-...` | `claude-sonnet-4-6` |
210
- | 🟢 **OpenAI** | `export OPENAI_API_KEY=sk-...` | `gpt-4.1` |
211
- | 🔴 **Vertex AI** | `export VERTEX_PROJECT_ID=my-project` | `claude-sonnet-4-6` |
212
- | ⚪ **Custom endpoint** | `OPENAI_API_KEY` + `OPENAI_BASE_URL` | `gpt-4.1` |
167
+ No API key? No problem. Caliber works with your existing AI tool subscription:
168
+
169
+ | Provider | Setup | Default Model |
170
+ |---|---|---|
171
+ | **Claude Code** (your seat) | `caliber config` → Claude Code | Inherited from Claude Code |
172
+ | **Cursor** (your seat) | `caliber config` → Cursor | Inherited from Cursor |
173
+ | **Anthropic** | `export ANTHROPIC_API_KEY=sk-ant-...` | `claude-sonnet-4-6` |
174
+ | **OpenAI** | `export OPENAI_API_KEY=sk-...` | `gpt-4.1` |
175
+ | **Vertex AI** | `export VERTEX_PROJECT_ID=my-project` | `claude-sonnet-4-6` |
176
+ | **Custom endpoint** | `OPENAI_API_KEY` + `OPENAI_BASE_URL` | `gpt-4.1` |
213
177
 
214
178
  Override the model for any provider: `export CALIBER_MODEL=<model-name>` or use `caliber config`.
215
179
 
216
- Configuration is stored in `~/.caliber/config.json` with restricted permissions (`0600`). 🔒 API keys are never written to project files.
180
+ Caliber uses a **two-tier model system** — lightweight tasks (classification, scoring) auto-use a faster model, while heavy tasks (generation, refinement) use the default. This keeps costs low and speed high.
181
+
182
+ Configuration is stored in `~/.caliber/config.json` with restricted permissions (`0600`). API keys are never written to project files.
217
183
 
218
184
  <details>
219
185
  <summary>Vertex AI advanced setup</summary>
@@ -237,18 +203,19 @@ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
237
203
  <details>
238
204
  <summary>Environment variables reference</summary>
239
205
 
240
- | Variable | Purpose |
241
- | -------------------------------- | --------------------------------------- |
242
- | `ANTHROPIC_API_KEY` | Anthropic API key |
243
- | `OPENAI_API_KEY` | OpenAI API key |
244
- | `OPENAI_BASE_URL` | Custom OpenAI-compatible endpoint |
245
- | `VERTEX_PROJECT_ID` | GCP project ID for Vertex AI |
246
- | `VERTEX_REGION` | Vertex AI region (default: `us-east5`) |
247
- | `VERTEX_SA_CREDENTIALS` | Service account JSON (inline) |
248
- | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON file path |
249
- | `CALIBER_USE_CLAUDE_CLI` | Use Claude Code CLI (`1` to enable) |
250
- | `CALIBER_USE_CURSOR_SEAT` | Use Cursor subscription (`1` to enable) |
251
- | `CALIBER_MODEL` | Override model for any provider |
206
+ | Variable | Purpose |
207
+ |---|---|
208
+ | `ANTHROPIC_API_KEY` | Anthropic API key |
209
+ | `OPENAI_API_KEY` | OpenAI API key |
210
+ | `OPENAI_BASE_URL` | Custom OpenAI-compatible endpoint |
211
+ | `VERTEX_PROJECT_ID` | GCP project ID for Vertex AI |
212
+ | `VERTEX_REGION` | Vertex AI region (default: `us-east5`) |
213
+ | `VERTEX_SA_CREDENTIALS` | Service account JSON (inline) |
214
+ | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON file path |
215
+ | `CALIBER_USE_CLAUDE_CLI` | Use Claude Code CLI (`1` to enable) |
216
+ | `CALIBER_USE_CURSOR_SEAT` | Use Cursor subscription (`1` to enable) |
217
+ | `CALIBER_MODEL` | Override model for any provider |
218
+ | `CALIBER_FAST_MODEL` | Override fast model for any provider |
252
219
 
253
220
  </details>
254
221
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rely-ai/caliber",
3
- "version": "1.18.8",
3
+ "version": "1.18.9",
4
4
  "description": "Analyze your codebase and generate optimized AI agent configs (CLAUDE.md, .cursorrules, skills) — no API key needed",
5
5
  "type": "module",
6
6
  "bin": {