Skip to content

Policies

Pavel Erokhin edited this page Nov 20, 2026 · 3 revisions

Русская версия

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.

Policies

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.

Which token limits L2 checks

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.

One set of policies for every repository

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 Lint

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.

Checks

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

Change a level

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.

Silence a check in a file

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 -->

Size limits

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 } } } }],
},

Adopt ctxray in an old repository

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.

Clone this wiki locally