Repository navigation
Policies
Every ctxray test checks two layers without a single test of yours. L1 Lint checks that the agent files parse, link, and stay within size limits. L2 Policy checks the rules your organisation sets for the context: token limits, banned and required MCP servers, files every repository must have. Both read files only, call no model, and finish in milliseconds, so they run on every merge request. This page covers policies, the lint checks and their levels, size limits, and the baseline that lets an old repository adopt ctxray without fixing everything first.
A policy is an entry under policies in the config. Each one names itself and says what it checks:
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
harnesses: { "claude-code": {}, codex: {} },
policies: [
{ id: "context-budget", maxTokens: { total: 25000, rules: 8000 } },
{ id: "no-public-mcp", denyMcp: ["jira"], requireMcp: ["github"] },
{ id: "agents-md", severity: "warning", requireFiles: ["AGENTS.md", "docs/adr/*.md"] },
],
});| Field | Type | Default | Means |
|---|---|---|---|
id |
string |
required | A unique name. The report shows it, and an inherited policy with the same id merges with this one |
severity |
"error" or "warning"
|
error |
warning reports what it found without failing the run |
harnesses |
harness ids | every harness of the run | The harnesses the policy applies to |
maxTokens |
{ total?, system?, rules?, skills?, mcp?, commands?, tools? } |
– | Token limits, for the whole context and per component |
denyMcp |
string[] |
– | MCP servers that must not be configured |
requireMcp |
string[] |
– | MCP servers that must be configured |
requireFiles |
string[] |
– | Files that must exist, relative to the project root. A glob passes when any file matches it |
A policy has to check something: one with none of maxTokens, denyMcp, requireMcp, and requireFiles stops the run, and ctxray names the policy that checks nothing. Two policies with the same id in one file are an error too.
ctxray checks each policy on every harness it covers and reports it under the policy's id:
ctxray checks
L2 policy context-budget
claude-code ✓ codex ✓
L2 policy no-public-mcp
claude-code ✗ codex ✗
L2 policy agents-md
claude-code ✓ 1 warning codex ✓ 1 warning
✗ claude-code › L2 policy › no-public-mcp
MCP server “jira” isn't allowed
⚠ claude-code › L2 policy › agents-md
docs/adr/*.md is missing
denyMcp and requireMcp compare server names with the MCP servers each harness's own config files declare in the project, like .mcp.json for Claude Code or .codex/config.toml for Codex.
L2 reads files only. It knows what the rules, skills, and commands cost, but not the system prompt, the built-in tools, or the MCP tool schemas: only a running harness sends those. So the limits split:
| Limit | Checked in |
|---|---|
rules, skills, commands
|
L2, on the context a session starts with in the project root, and again in L4 |
total, system, tools, mcp
|
L4 only |
In L4, ctxray launches each harness once against its mock model and holds the first request to every maxTokens limit. That check costs nothing and needs no test, only a harness ctxray can launch, as Harnesses describes. When L4 doesn't run, these limits stay unchecked. A policy with nothing but L4 limits doesn't show up under L2 at all, and one with both kinds checks its static part in L2. The L4 check also warns when the same instructions reach the model twice.
L2 counts tokens on your machine, so they're estimates. A limit close to the real size may pass in L2 and fail in L4, where the harness's own request counts. Configuration explains exactTokens.
Publish your policies once, as an npm package or a shared file, and let each repository extend it:
// a project's ctxray.config.ts
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
extends: "@acme/ctxray-config",
harnesses: { "claude-code": {}, codex: {} },
policies: [{ id: "agents-md", severity: "warning" }],
});A project's policy with an inherited id merges into it field by field. Here the project keeps the organisation's requireFiles and only lowers the severity. A policy with a new id joins the list. Enterprise shows the package side, and Configuration the full merge rules.
L1 runs on every harness of the run. It checks what each harness reads: instruction files, rules, skills, commands, and MCP configs. An error fails the run, and a warning shows up without failing it:
⚠ claude-code › L1 lint › project files
CLAUDE.md:8 The link to missing.md leads nowhere broken-link
The last word of a finding is its id. The config and the suppression comments name checks by it.
| Id | Default | Finds |
|---|---|---|
frontmatter |
error in a skill, warning in a Claude Code rule | Frontmatter that isn't valid YAML, so the harness ignores it, or one indented with tabs, which Claude Code and Codex refuse in a skill |
loose-frontmatter |
warning | Frontmatter that isn't valid YAML, which Claude Code and Codex still read line by line and stricter tools don't |
rule-field |
warning | A Claude Code rule field other than paths, or a Cursor alwaysApply that's a string like "true": both do nothing |
too-large |
error | A file over 4 MiB, which Claude Code skips entirely |
import-missing |
warning | An @import of a file that doesn't exist |
import-depth |
warning | An @import nested too deep to ever load |
shadowed-command |
warning | A command a skill of the same name hides |
no-description |
warning | A skill without a description, which the model has little to pick by |
long-description |
warning | A skill description longer than its harness's listing keeps: 1,536 characters in Claude Code, 1,024 in Codex |
skill-listing |
warning | The project's skills don't fit the harness's skill listing. Claude Code gives it 1% of the model's window and leaves the skills that don't fit with their name only, so the model can't pick them by what they do. Codex gives it 2% and cuts every description short, and drops skills once even the names don't fit |
bad-json |
error | A JSON config that doesn't parse |
bad-toml |
error | A TOML config that doesn't parse, so the harness ignores it |
mcp-transport |
error | An MCP server with neither command nor url
|
empty-file |
warning | An empty instruction file the harness skips |
shadowed-file |
warning | An instruction file Codex skips because another one in the folder wins |
skill-field |
error | A skill without the name or description the harness needs |
codex-budget |
warning | AGENTS.md files over Codex's byte budget, 32 KiB unless project_doc_max_bytes says otherwise |
bad-glob |
error | A glob that's empty, has an unclosed bracket or brace, or points outside its folder with ..
|
skill-name |
warning | A skill name only some harnesses accept: use lowercase letters, digits, and hyphens, up to 64 |
skill-folder-name |
warning | A skill whose name differs from its folder's |
duplicate-skill |
warning | Two skills with one name in one folder |
duplicate-text |
warning | Two instruction files with the same text, which the model reads twice |
broken-link |
warning | A link to a file that doesn't exist |
dead-rule |
warning | A rule whose globs match no file in the repository, so it never loads |
size |
per limits | A file over a size limit |
unread |
error | An agent file no harness reads and no read file links to, so it reaches no model |
other-harness |
warning | A file only a harness outside the run reads |
harness-differences |
warning | A file some harnesses of the run read and others don't, with nothing they read saying the same |
misnamed-file |
error | A file named or placed almost right, which the harness never reads: AGENT.md, .cursorrule, .claude/rule/, .agent/skills/, mcp.json in the root, a skill as a lone .md file, a .md rule in .cursor/rules. The finding names the file the harness looks for |
letter-case |
error | A name that differs only in letter case, like claude.md, .Claude/, or skill.md: macOS and Windows may open it under the right name, Linux and CI don't |
absolute-path |
warning | A path into a home folder or onto a Windows drive, like /Users/…, /home/…, ~/…, or C:\…, in an @import, a link, paths or globs, or an MCP config: the team and CI don't have it |
byte-order-mark |
error | A SKILL.md that starts with a byte order mark, which Codex skips |
not-shared |
warning | A file a harness reads on your machine that the team and CI never get: hidden by .gitignore, not committed yet, or behind a symlink that leaves the repository. CLAUDE.local.md stays out |
broken-symlink |
error | An agent file or harness folder whose symlink points nowhere |
secret |
error | A key, a token, a password, or a private key in a file the model reads. The finding names its kind and line, never the value |
personal-data |
warning | An email, a phone number, or a card number in a file the model reads |
lint.rules sets the level of any check by its id: error, warning, or off.
export default defineConfig({
lint: {
rules: {
"broken-link": "error",
"harness-differences": "off",
"skill-name": { level: "warning" },
},
ignore: ["docs/archive/**"],
errorOnWarnings: false,
overrides: [
{ include: ["legacy/**"], rules: { "dead-rule": "off" } },
{ include: [".claude/skills/**"], harnesses: ["codex"], rules: { "skill-field": "warning" } },
],
},
});| Key | Means |
|---|---|
rules |
The level of each check, by its id |
ignore |
Globs from the project root: L1 skips these files entirely |
errorOnWarnings |
Every warning fails the run, as an error would. --error-on-warnings turns it on for one run |
overrides |
Levels and limits for some files: include (globs, required), harnesses (all by default), rules, and limits
|
ctxray applies rules first, then each override that covers the file, in order: the last level wins. A glob matches a file by its own path and by the real path behind a symlink.
--ignore-harness-differences, CTXRAY_IGNORE_HARNESS_DIFFERENCES=1, and ignoreHarnessDifferences: true all turn off harness-differences without touching the lint config.
A comment in a Markdown file silences checks on that file alone. Without ids it silences every check, and the text after a colon tells reviewers why:
<!-- ctxray-ignore -->
<!-- ctxray-ignore broken-link, size: the links point to the generated API docs -->L1 measures each skill body, each command body, and each instruction file in lines, characters, and tokens. Tokens are counted with the local o200k tokenizer, whatever the harness. Over the warning threshold L1 warns, over error it fails.
| Kind | Applies to | Built-in limit |
|---|---|---|
skill |
a SKILL.md body |
warning over 500 lines |
command |
a command's body | warning over 500 lines |
instruction |
CLAUDE.md, AGENTS.md, a rule, any other instruction file | warning over 40,000 characters |
Anthropic asks for a SKILL.md under 500 lines, and Claude Code warns about instructions over 40,000 characters. Set your own under limits:
export default defineConfig({
limits: {
skill: { lines: { warning: 300, error: 500 }, tokens: { error: 5000 } },
instruction: { chars: { warning: 20000, error: 40000 } },
command: false,
},
});A threshold you don't name keeps its built-in value. false turns one threshold off, and false for a whole kind turns off every size check of that kind. A lint override with limits sets limits for some folders, over the project's:
lint: {
overrides: [{ include: ["docs/agents/**"], limits: { instruction: { chars: { warning: 60000 } } } }],
},An old repository rarely passes L1 and L2 on day one. Fixing everything before the first green run stalls the adoption. A baseline records today's findings, so the run fails only on new ones:
ctxray baseline ctxray.baseline.json: 11 findings
Commit the file. ctxray test reads it, and ctxray baseline writes it again once you fix some
ctxray test reads ctxray.baseline.json from the project root and drops every finding it knows. A check whose remaining findings are all known passes, and the summary counts what the baseline held back:
Baseline 11 findings ctxray.baseline.json knows didn't fail the run
A finding is known by its harness, check, id, file, and details, without a line number, so edits above it don't make it new. Fix some findings, then run ctxray baseline again to shrink the file. --harness limits the baseline to some harnesses, and --config picks the config. The baseline covers L1 and L2 only: the L4 check of the starting context always counts.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие