https://github.com/caliber-ai-org/ai-setup
Continuously sync your AI setups with one command. Codebase tailor suited agent skills, MCPs and config files for Claude Code, Cursor, and Codex.
https://github.com/caliber-ai-org/ai-setup
agent-config ai-agents anthropic claude-code claude-md cli codex cursor cursorrules developer-tools llm mcp openai openai-codex skills
Last synced: 5 days ago
JSON representation
Continuously sync your AI setups with one command. Codebase tailor suited agent skills, MCPs and config files for Claude Code, Cursor, and Codex.
- Host: GitHub
- URL: https://github.com/caliber-ai-org/ai-setup
- Owner: caliber-ai-org
- License: mit
- Created: 2026-03-10T19:39:38.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-04-08T09:20:51.000Z (10 days ago)
- Last Synced: 2026-04-08T11:29:52.955Z (10 days ago)
- Topics: agent-config, ai-agents, anthropic, claude-code, claude-md, cli, codex, cursor, cursorrules, developer-tools, llm, mcp, openai, openai-codex, skills
- Language: TypeScript
- Homepage: https://caliber-ai.dev
- Size: 116 MB
- Stars: 632
- Watchers: 10
- Forks: 81
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-ai-agents-2026 - Caliber
- awesome-vibecoding - **Caliber**
- awesome-claude-code-toolkit - caliber - - | CLI that fingerprints projects and generates AI agent configs (CLAUDE.md, skills, AGENTS.md). Scores quality, auto-refreshes, supports Claude Code + Cursor + Codex | (Ecosystem / Quick Setup with cc-safe-setup)
README
# Caliber
**Hand-written `CLAUDE.md` files go stale the moment you refactor.** Your AI agent hallucinates paths that no longer exist, misses new dependencies, and gives advice based on yesterday's architecture. Caliber generates and maintains your AI context files (`CLAUDE.md`, `.cursor/rules/`, `AGENTS.md`, `copilot-instructions.md`) so they stay accurate as your code evolves — and keeps every agent on your team in sync, whether they use Claude Code, Cursor, Codex, OpenCode, or GitHub Copilot.
## Before / After
Most repos start with a hand-written `CLAUDE.md` and nothing else. Here's what Caliber finds — and fixes:
```
Before After /setup-caliber
────────────────────────────── ──────────────────────────────
Agent Config Score 35 / 100 Agent Config Score 94 / 100
Grade D Grade A
FILES & SETUP 6 / 25 FILES & SETUP 24 / 25
QUALITY 12 / 25 QUALITY 22 / 25
GROUNDING 7 / 20 GROUNDING 19 / 20
ACCURACY 5 / 15 ACCURACY 13 / 15
FRESHNESS 5 / 10 FRESHNESS 10 / 10
BONUS 0 / 5 BONUS 5 / 5
```
Scoring is deterministic — no LLM, no API calls. It cross-references your config files against your actual project filesystem: do referenced paths exist? Are code blocks present? Is there config drift since your last commit?
```bash
caliber score --compare main # See how your branch changed the score
```
## Get Started
Requires **Node.js >= 20**.
```bash
npx @rely-ai/caliber bootstrap
```
Then, in your terminal (not the IDE chat), start a Claude Code or Cursor CLI session and type:
> **/setup-caliber**
Your agent detects your stack, generates tailored configs for every platform your team uses, sets up pre-commit hooks, and enables continuous sync — all from inside your normal workflow.
**Don't use Claude Code or Cursor?** Run `caliber init` instead — it's the same setup as a CLI wizard. Works with any LLM provider: bring your own Anthropic, OpenAI, or Vertex AI key.
> **Your code stays on your machine.** Bootstrap is 100% local — no LLM calls, no code sent anywhere. Generation uses your own AI subscription or API key. Caliber never sees your code.
Windows Users
Caliber works on Windows with a few notes:
- **Run from your terminal** (PowerShell, CMD, or Git Bash) — not from inside an IDE chat window. Open a terminal, `cd` into your project folder, then run `npx @rely-ai/caliber bootstrap`.
- **Git Bash is recommended.** Caliber's pre-commit hooks and auto-sync scripts use shell syntax. Git for Windows includes Git Bash, which handles this automatically. If you only use PowerShell, hooks may be skipped silently.
- **Cursor Agent CLI:** If prompted to install it, download from [cursor.com/downloads](https://www.cursor.com/downloads) instead of the `curl | bash` command shown on macOS/Linux. Then run `agent login` in your terminal to authenticate.
- **One terminal at a time.** Avoid running Caliber from multiple terminals simultaneously — this can cause conflicting state and unexpected provider detection.
## Audits first, writes second
Caliber never overwrites your existing configs without asking. The workflow mirrors code review:
1. **Score** — read-only audit of your current setup
2. **Propose** — generate or improve configs, shown as a diff
3. **Review** — accept, refine via chat, or decline each change
4. **Backup** — originals saved to `.caliber/backups/` before every write
5. **Undo** — `caliber undo` restores everything to its previous state
If your existing config scores **95+**, Caliber skips full regeneration and applies targeted fixes to the specific checks that are failing.
## How It Works
Bootstrap gives your agent the `/setup-caliber` skill. Your agent analyzes your project — languages, frameworks, dependencies, architecture — generates configs, and installs hooks. From there, it's a loop:
```
npx @rely-ai/caliber bootstrap ← one-time, 2 seconds
│
▼
agent runs /setup-caliber ← agent handles everything
│
▼
┌──── configs generated ◄────────────┐
│ │ │
│ ▼ │
│ your code evolves │
│ (new deps, renamed files, │
│ changed architecture) │
│ │ │
│ ▼ │
└──► caliber refresh ──────────────►─┘
(auto, on every commit)
```
Pre-commit hooks run the refresh loop automatically. New team members get nudged to bootstrap on their first session.
### What It Generates
**Claude Code**
- `CLAUDE.md` — Project context, build/test commands, architecture, conventions
- `CALIBER_LEARNINGS.md` — Patterns learned from your AI coding sessions
- `.claude/skills/*/SKILL.md` — Reusable skills ([OpenSkills](https://agentskills.io) format)
- `.mcp.json` — Auto-discovered MCP server configurations
- `.claude/settings.json` — Permissions and hooks
**Cursor**
- `.cursor/rules/*.mdc` — Modern rules with frontmatter (description, globs, alwaysApply)
- `.cursor/skills/*/SKILL.md` — Skills for Cursor
- `.cursor/mcp.json` — MCP server configurations
**OpenAI Codex**
- `AGENTS.md` — Project context for Codex
- `.agents/skills/*/SKILL.md` — Skills for Codex
**OpenCode**
- `AGENTS.md` — Project context (shared with Codex when both are targeted)
- `.opencode/skills/*/SKILL.md` — Skills for OpenCode
**GitHub Copilot**
- `.github/copilot-instructions.md` — Project context for Copilot
## Key Features
Any Codebase
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.
Any AI Tool
`caliber bootstrap` auto-detects which agents you have installed. For manual control:
```bash
caliber init --agent claude # Claude Code only
caliber init --agent cursor # Cursor only
caliber init --agent codex # Codex only
caliber init --agent opencode # OpenCode only
caliber init --agent github-copilot # GitHub Copilot only
caliber init --agent all # All platforms
caliber init --agent claude,cursor # Comma-separated
```
Chat-Based Refinement
Not happy with the generated output? During review, refine via natural language — describe what you want changed and Caliber iterates until you're satisfied.
MCP Server Discovery
Caliber detects the tools your project uses (databases, APIs, services) and auto-configures matching MCP servers for Claude Code and Cursor.
Deterministic Scoring
`caliber score` evaluates your config quality without any LLM calls — purely by cross-referencing config files against your actual project filesystem.
| Category | Points | What it checks |
|---|---|---|
| **Files & Setup** | 25 | Config files exist, skills present, MCP servers, cross-platform parity |
| **Quality** | 25 | Code blocks, concise token budget, concrete instructions, structured headings |
| **Grounding** | 20 | Config references actual project directories and files |
| **Accuracy** | 15 | Referenced paths exist on disk, config freshness vs. git history |
| **Freshness & Safety** | 10 | Recently updated, no leaked secrets, permissions configured |
| **Bonus** | 5 | Auto-refresh hooks, AGENTS.md, OpenSkills format |
Every failing check includes structured fix data — when `caliber init` runs, the LLM receives exactly what's wrong and how to fix it.
Session Learning
Caliber watches your AI coding sessions and learns from them. Hooks capture tool usage, failures, and your corrections — then an LLM distills operational patterns into `CALIBER_LEARNINGS.md`.
```bash
caliber learn install # Install hooks for Claude Code and Cursor
caliber learn status # View hook status, event count, and ROI summary
caliber learn finalize # Manually trigger analysis (auto-runs on session end)
caliber learn remove # Remove hooks
```
Learned items are categorized by type — **[correction]**, **[gotcha]**, **[fix]**, **[pattern]**, **[env]**, **[convention]** — and automatically deduplicated.
Auto-Refresh
Keep configs in sync with your codebase automatically:
| Hook | Trigger | What it does |
|---|---|---|
| **Git pre-commit** | Before each commit | Refreshes docs and stages updated files |
| **Claude Code session end** | End of each session | Runs `caliber refresh` and updates docs |
| **Learning hooks** | During each session | Captures events for session learning |
```bash
caliber hooks --install # Enable refresh hooks
caliber hooks --remove # Disable refresh hooks
```
The `refresh` command analyzes your git diff (committed, staged, and unstaged changes) and updates config files to reflect what changed.
Team Onboarding
When Caliber is set up in a repo, it automatically nudges new team members to configure it on their machine. A lightweight session hook checks whether the pre-commit hook is installed and prompts setup if not — no manual coordination needed.
Fully Reversible
- **Automatic backups** — originals saved to `.caliber/backups/` before every write
- **Score regression guard** — if a regeneration produces a lower score, changes are auto-reverted
- **Full undo** — `caliber undo` restores everything to its previous state
- **Clean uninstall** — `caliber uninstall` removes everything Caliber added (hooks, generated sections, skills, learnings) while preserving your own content
- **Dry run** — preview changes with `--dry-run` before applying
## Commands
| Command | Description |
|---|---|
| `caliber bootstrap` | Install agent skills — the fastest way to get started |
| `caliber init` | Full setup wizard — analyze, generate, review, install hooks |
| `caliber score` | Score config quality (deterministic, no LLM) |
| `caliber score --compare ` | Compare current score against a git ref |
| `caliber regenerate` | Re-analyze and regenerate configs (aliases: `regen`, `re`) |
| `caliber refresh` | Update docs based on recent code changes |
| `caliber skills` | Discover and install community skills |
| `caliber learn` | Session learning — install hooks, view status, finalize analysis |
| `caliber hooks` | Manage auto-refresh hooks |
| `caliber config` | Configure LLM provider, API key, and model |
| `caliber status` | Show current setup status |
| `caliber uninstall` | Remove all Caliber resources from a project |
| `caliber undo` | Revert all changes made by Caliber |
## FAQ
Does it overwrite my existing configs?
No. Caliber shows you a diff of every proposed change. You accept, refine, or decline each one. Originals are backed up automatically.
Does it need an API key?
**Bootstrap & scoring:** No. Both run 100% locally with no LLM.
**Generation** (via `/setup-caliber` or `caliber init`): Uses your existing Claude Code or Cursor subscription (no API key needed), or bring your own key for Anthropic, OpenAI, or Vertex AI.
What's the difference between bootstrap and init?
`caliber bootstrap` installs agent skills in 2 seconds — your agent then runs `/setup-caliber` to handle the rest from inside your session. `caliber init` is the full interactive wizard for users who prefer a CLI-driven setup. Both end up in the same place.
What if I don't like what it generates?
Refine it via chat during review, or decline the changes entirely. If you already accepted, `caliber undo` restores everything. You can also preview with `--dry-run`.
Does it work with monorepos?
Yes. Run `caliber init` from any directory. `caliber refresh` can update configs across multiple repos when run from a parent directory.
Does it send my code anywhere?
Scoring is fully local. Generation sends a project summary (languages, structure, dependencies — not source code) to whatever LLM provider you configure — the same provider your AI editor already uses. Anonymous usage analytics (no code, no file contents) can be disabled via `caliber config`.
## LLM Providers
No API key? No problem. Caliber works with your existing AI tool subscription:
| Provider | Setup | Default Model |
|---|---|---|
| **Claude Code** (your seat) | `caliber config` → Claude Code | Inherited from Claude Code |
| **Cursor** (your seat) | `caliber config` → Cursor | Inherited from Cursor |
| **Anthropic** | `export ANTHROPIC_API_KEY=sk-ant-...` | `claude-sonnet-4-6` |
| **OpenAI** | `export OPENAI_API_KEY=sk-...` | `gpt-5.4-mini` |
| **Vertex AI** | `export VERTEX_PROJECT_ID=my-project` | `claude-sonnet-4-6` |
| **Custom endpoint** | `OPENAI_API_KEY` + `OPENAI_BASE_URL` | `gpt-5.4-mini` |
Override the model for any provider: `export CALIBER_MODEL=` or use `caliber config`.
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.
Configuration is stored in `~/.caliber/config.json` with restricted permissions (`0600`). API keys are never written to project files.
Vertex AI advanced setup
```bash
# Custom region
export VERTEX_PROJECT_ID=my-gcp-project
export VERTEX_REGION=europe-west1
# Service account credentials (inline JSON)
export VERTEX_PROJECT_ID=my-gcp-project
export VERTEX_SA_CREDENTIALS='{"type":"service_account",...}'
# Service account credentials (file path)
export VERTEX_PROJECT_ID=my-gcp-project
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```
Environment variables reference
| Variable | Purpose |
|---|---|
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `OPENAI_API_KEY` | OpenAI API key |
| `OPENAI_BASE_URL` | Custom OpenAI-compatible endpoint |
| `VERTEX_PROJECT_ID` | GCP project ID for Vertex AI |
| `VERTEX_REGION` | Vertex AI region (default: `us-east5`) |
| `VERTEX_SA_CREDENTIALS` | Service account JSON (inline) |
| `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON file path |
| `CALIBER_USE_CLAUDE_CLI` | Use Claude Code CLI (`1` to enable) |
| `CALIBER_USE_CURSOR_SEAT` | Use Cursor subscription (`1` to enable) |
| `CALIBER_MODEL` | Override model for any provider |
| `CALIBER_FAST_MODEL` | Override fast model for any provider |
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
```bash
git clone https://github.com/caliber-ai-org/ai-setup.git
cd caliber
npm install
npm run dev # Watch mode
npm run test # Run tests
npm run build # Compile
```
Uses [conventional commits](https://www.conventionalcommits.org/) — `feat:` for features, `fix:` for bug fixes.
## Add a Caliber badge to your repo
After scoring your project, add a badge to your README:
Copy this markdown and replace `94` with your actual score:
```
```
Color guide: `brightgreen` (90+), `green` (70-89), `yellow` (40-69), `red` (<40).
## License
MIT