Use with AI coding assistants

Give Claude Code, Cursor, GitHub Copilot and other assistants the facts they need to write CoreValue integrations correctly.

Coding assistants write integration code from what they already know, and they do not know CoreValue. Add the instructions below to your repository and the assistant will route requests through the gateway, send the right key in the right header, and tag spend the way your budgets and reports expect.

The same text works for every assistant; only the file it goes in changes.

The instructions

## CoreValue

This project sends LLM requests through the CoreValue gateway, which checks
budgets before each request and records its cost. Docs:
https://docs.corevalue.dev (index for tools: https://docs.corevalue.dev/llms.txt)

### Connecting
- Never put a provider key (OpenAI, Anthropic, Google) in this codebase. Provider
  keys are stored in CoreValue. The app sends only its CoreValue key, from the
  `COVA_API_KEY` environment variable. It starts with `sk-cova-`.
- OpenAI SDK: `base_url="https://gateway.corevalue.dev/v1"`, `api_key=COVA_API_KEY`.
- Other providers through the OpenAI SDK: `base_url="https://gateway.corevalue.dev/gateway/v1"`
  and a provider prefix on the model, e.g. `groq/llama-3.3-70b-versatile`.
  Prefixes are ignored on the plain `/v1` base URL.
- Anthropic SDK: `base_url="https://gateway.corevalue.dev"` (no `/v1`),
  `api_key=COVA_API_KEY`. Use `api_key`, never `auth_token`: the gateway reads
  the key from `x-api-key`.
- Google Gen AI SDK: `apiKey=COVA_API_KEY`, `httpOptions.baseUrl="https://gateway.corevalue.dev"`.

### Attributing spend (request headers)
- `Cova-Customer-Id`: which of our customers the request serves. Budgets and
  margin reports group by it.
- `Cova-Feature-Id`: which feature made the request, e.g. `support-bot`.
- `Cova-Team-Id`: which team the spend belongs to, when one key serves several.
- `Cova-Session-Id`: the same value on every request of one task or agent run.
- `Cova-Property-<Name>`: any other label, e.g. `Cova-Property-Env: production`.
Set shared ones once with the SDK's default headers.

### Responses
- `Cova-Request-Cost` header: the request's cost in US dollars (non-streaming).
- `Cova-Id` header: the request id.
- A refused request returns HTTP 429 when a budget is set to block. Handle it
  like a rate limit; the SDKs retry 429 automatically.
- `Cova-Fallbacks: ["model-a", "model-b"]` tries other models in order if the
  first returns a retryable error.

For Claude Code

Paste the instructions into CLAUDE.md at the root of the repository. Claude Code reads it at the start of every session.

If you also run Claude Code itself through CoreValue, see Claude Code.

For Cursor

Save the instructions as .cursor/rules/corevalue.mdc, with this header above them so the rule is always applied:

---
description: How this project calls LLMs through CoreValue
alwaysApply: true
---

For GitHub Copilot

Paste the instructions into .github/copilot-instructions.md. Copilot adds the file to every chat in the repository.

For other assistants

Codex and other agents that read AGENTS.md take the same text there. Any tool that can fetch a URL can also read the docs directly:

URL	What it is
`/llms.txt`	An index of every page, with links and descriptions.
`/llms-full.txt`	The text of every page in one file.

Point the assistant at llms.txt when it needs a detail the instructions above leave out, such as a header's exact validation rules or a provider prefix.