<p align="center"> <img src="assets/logo-dark.svg" alt="Caliber" width="220"> </p>

Caliber

Hand-written CLAUDE.md files go stale the moment you refactor — Caliber keeps every agent's context accurate as the code changes.

<p align="center"> <img src="assets/what-you-get.svg" alt="What you get: fresh agent context files, sync across Claude Cursor Codex OpenCode and Copilot, and optional Jev compaction without summarizing" width="900"> </p> <p align="center"> <img src="assets/demo-header.gif" alt="Caliber product demo" width="900"> </p> <p align="center"> <a href="https://www.npmjs.com/package/@rely-ai/caliber"><img src="https://img.shields.io/npm/v/@rely-ai/caliber" alt="npm version"></a> <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@rely-ai/caliber" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@rely-ai/caliber" alt="node"></a> <img src="https://img.shields.io/badge/caliber-94%2F100-brightgreen" alt="Caliber Score"> <img src="https://img.shields.io/badge/Claude_Code-supported-blue" alt="Claude Code"> <img src="https://img.shields.io/badge/Cursor-supported-blue" alt="Cursor"> <img src="https://img.shields.io/badge/Codex-supported-blue" alt="Codex"> <img src="https://img.shields.io/badge/OpenCode-supported-blue" alt="OpenCode"> <img src="https://img.shields.io/badge/GitHub_Copilot-supported-blue" alt="GitHub Copilot"> </p>

Start

Requires Node.js >= 20.

npx @rely-ai/caliber bootstrap

Then, in your terminal (not the IDE chat), start Claude Code or Cursor CLI and type:

/setup-caliber

The agent detects the stack, writes CLAUDE.md / Cursor rules / AGENTS.md / Copilot instructions, and installs the hooks.

No Claude Code or Cursor? caliber init is the same setup as a CLI wizard — Anthropic, OpenAI, MiniMax, or Vertex, your key.

Your code stays on your machine. Bootstrap is local — no LLM calls, no code sent anywhere. Generation uses your seat or your key. Caliber never sees your source.

<details> <summary><strong>Windows</strong></summary>

• Run from your terminal (PowerShell, CMD, or Git Bash) — not from an IDE chat. cd into the project, then npx @rely-ai/caliber bootstrap.
• Git Bash is recommended. Pre-commit hooks and auto-sync scripts use shell syntax. PowerShell-only setups may skip hooks silently.
• Cursor Agent CLI: If prompted to install it, download from cursor.com/downloads instead of the macOS/Linux curl | bash. Then agent login.
• One terminal at a time. Two Caliber processes in one repo will fight over provider detection.

</details>

Proof

A typical hand-written CLAUDE.md and nothing else. Scoring is filesystem math — no LLM, no API calls. It checks whether referenced paths exist, whether code blocks are present, and whether the config drifted since the last commit.

  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

caliber score --compare main    # how this branch moved the score

Write a skill once. Every agent gets it.

<p align="center"> <img src="assets/sync-flow.svg" alt="A skill written in Claude Code is mirrored by caliber sync into Cursor, Codex, OpenCode, and Copilot native folders" width="900"> </p>

caliber sync — no LLM, cheap enough for every session start.

caliber sync                    # mirror into every detected agent
caliber sync --status           # what each agent currently holds
caliber sync --dry-run          # preview without writing
caliber sync --from cursor      # pick the source of truth

<details> <summary>What sync writes, what it refuses to clobber</summary>

Caliber Sync

  Source: Claude Code — 4 item(s)
  Targets: Cursor, Codex, GitHub Copilot

  wrote  .cursor/skills/deploy/SKILL.md
  wrote  .cursor/rules/house-style.mdc
  wrote  .cursor/mcp.json
  wrote  .agents/skills/deploy/SKILL.md
  wrote  .github/instructions/deploy.instructions.md
  skipped  mcp:linear for codex — Codex MCP servers are configured globally

refresh rewrites the prose documents. sync owns the artifacts. They stay in their lanes.

Providers are not symmetric, so sync degrades instead of dropping. Copilot has no skills directory — a skill becomes .github/instructions/*.instructions.md with applyTo from the skill's paths. Codex has no plugin system — a plugin expands into its skills. Anything that cannot be represented is reported with a reason.

Hand edits are never clobbered. Sync hashes every file it writes. A file you edited is a conflict until you pass --force.

Two optional hooks (caliber hooks) keep it continuous:

| Hook | Effect | |---|---| | Agent sync (SessionStart) | Every agent starts holding the same skills and rules | | Agent sync (on edit) | Editing a skill in one agent mirrors it immediately |

The on-edit hook is path-filtered to provider skill/rule directories, so ordinary edits cost nothing.

</details>

Compact without summarizing

<p align="center"> <img src="assets/compaction-compare.svg" alt="Left: a lossy built-in summary drops paths and errors. Right: Jev drops stale tool calls and results; user and assistant text stay verbatim" width="900"> </p>

TypeSafe's Jev scores each tool call and result. Stale ones drop. Everything kept stays byte-for-byte verbatim.

BYOK: AI_GATEWAY_API_KEY is a Vercel AI Gateway key. TYPESAFE_API_KEY is a TypeSafe key. They authenticate different hosts and are not interchangeable. Caliber does not ship, share, or proxy either.

export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1   # function hooks are early-access, off by default
export AI_GATEWAY_API_KEY=...                # Vercel AI Gateway — not a TypeSafe key
# or: export TYPESAFE_API_KEY=...            # direct TypeSafe System One

claude plugin marketplace add caliber-ai-org/ai-setup
claude plugin install caliber-jev-compaction@caliber

Or vendor it into a repo Caliber already set up:

caliber plugin install --dry-run   # print the loadable file tree, write nothing
caliber plugin install             # .claude/plugins/ + a local marketplace
caliber plugin list

5-minute install → key → live-gate → /compact: FUNCTIONAL_CHECKLIST.md.

Preview the same scoring without installing anything:

caliber compact            # report what would be dropped — read-only

Jev Compaction

  Messages:  248 -> 201
  Chars:     412,880 -> 190,344  (53.9% smaller)
  Calls:     96 scored — 41 kept, 23 results dropped, 26 calls dropped, 6 pinned

<details> <summary>Keys, fallback, and how to verify the real API</summary>

| Key | Host | Model | |---|---|---| | AI_GATEWAY_API_KEY | Vercel AI Gateway (/v4/ai/evaluation-model) | typesafe-ai/jev | | TYPESAFE_API_KEY | TypeSafe System One (api.typesafe.ai/v1/systemone) | jev-latest |

Set one in the environment, or enter it when claude plugin install prompts for gatewayApiKey / apiKey.

| Hook | What it does | |---|---| | session.compact | Substitutes the verbatim-trimmed transcript for Claude Code's summary | | turn.complete | Requests compaction once context passes compactAtPercent (60% by default) |

If Jev fails, the key is missing, the transcript will not fit the state budget, or the reduction is below minReductionRatio, the hook logs a fallback and delegates to Claude Code's built-in compaction — a bad Jev day degrades compaction, it does not break the session.

Configuration is plugin userConfig (apiKey, gatewayApiKey, gatewayBaseUrl, keepThreshold, preserveRecentMessages, compactAtPercent, minReductionRatio, maxStateTokens, maxRequestTokens, truncateHeadChars, model) — editable from Claude Code, not a Caliber config file.

Function hooks are an early-access Claude Code surface and stay off unless CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 is set. caliber plugin install prints the enable steps. Authored against Claude Code 2.1.274; revisit after an upgrade.

The unit suite substitutes the network. To hit the real Jev API:

# Direct TypeSafe System One (a TypeSafe key — not a Vercel key)
TYPESAFE_API_KEY=sk-... npm run e2e:jev

# Vercel AI Gateway — live gate for a Gateway key.
# A Gateway key 401s against api.typesafe.ai. Do not put it in TYPESAFE_API_KEY.
AI_GATEWAY_API_KEY=... npm run e2e:jev:gateway

e2e:jev:gateway skips when the key is unset (no fake pass). HTTP 403 "AI Gateway requires a valid credit card on file" is Vercel billing, not a Caliber bug. They never use a Caliber-hosted or shared secret.

caliber compact is the same scoring as a one-off report — useful before enabling the plugin, or from an agent that is not Claude Code. Below a 25% reduction it tells you compaction is not worth the request. It never rewrites the transcript.

caliber sync also installs a jev-compaction skill into every agent, which is the clearest demo of plugin expansion: Claude Code and Cursor get a skill, Copilot gets an instruction file.

The scoring library is bundled under src/vendor/ (MIT) — no extra install.

</details>

Agents beyond Claude Code

Claude Code is the only host with a function-hook plugin that can replace /compact in-session. Cursor agents, Codex, Grok Bot, and similar hosts have no such hook surface today — they get the same Jev scoring through the skill + CLI, and they apply the report themselves.

| Host | Auto /compact toast | CLI | --write | |---|---|---|---| | Claude Code | Yes (caliber-jev-compaction plugin) | caliber compact (auto-discovers ~/.claude/projects/…) | No — Claude owns the file; the plugin replaces the session | | Cursor agents | No | caliber compact --provider cursor --transcript <jsonl> | No — on-disk JSONL is unofficial, usually has tool_use without ids and no tool_result, so a rewrite would invent fields | | Grok Bot / Codex / others | No | caliber compact --provider generic --transcript <path> | Yes — documented caliber.transcript.v1 (or OpenAI-compatible messages JSON) has a proven round-trip |

--provider auto (default) detects the file. --transcript is required when the format is not Claude auto-discover.

# Report (any host). Same BYOK as the plugin.
export AI_GATEWAY_API_KEY=...          # Vercel AI Gateway — model typesafe-ai/jev
# or: export TYPESAFE_API_KEY=...      # direct TypeSafe — not a Gateway key

caliber compact --provider generic --transcript ./session.json
caliber compact --provider generic --transcript ./session.json --write
caliber compact --provider cursor --transcript ~/.cursor/projects/<slug>/agent-transcripts/<id>/<id>.jsonl

Prefer exporting caliber.transcript.v1 from the agent's in-memory conversation (tool results included). Cursor's ~/.cursor/projects/.../agent-transcripts/ file is a thin log: Jev cannot drop results that were never written. The synced jev-compaction skill tells the agent to export, run the CLI, and apply decisions — it does not create a Grok Bot / Cursor toast.

Generic envelope (also accepted: a bare Message[] JSON array, JSONL of those objects, or an OpenAI-compatible messages array):

{
  "schema": "caliber.transcript.v1",
  "messages": [
    { "role": "