Repository navigation
Commands RU
Все команды и параметры CLI ctxray. ctxray help <команда> или ctxray <команда> --help печатает тот же список на вашем языке, а эта страница ссылается на страницы, где подробно разобрано, что делает команда.
ctxray <команда> [подкоманда] [параметры]
| Команда | Что делает |
|---|---|
inspect |
Показать, что загружает каждый ИИ-харнесс и сколько это стоит в токенах |
test |
Запустить тесты *.ctxray.ts и собственные проверки ctxray |
baseline |
Записать находки L1 и L2 в ctxray.baseline.json: дальше прогон падает только на новых |
diff |
Показать, как loadout изменился относительно другой ревизии, по умолчанию origin/master, или сохранённого report.json
|
show-report |
Открыть последний отчёт в браузере, с обновлением во время прогона |
harness |
Поставить харнессы из ctxray.lock или закрепить новые |
mcp |
Отдать inspect, test и diff агенту по MCP через stdin и stdout |
cache |
Показать или почистить кеш харнессов, общий для всех проектов на машине |
doctor |
Проверить, что нужно для L4 и выше: git, сеть, кеш и закреплённые харнессы |
gen-prompts |
Написать промпты для L6 по описаниям правил и скиллов, в файл для ревью |
calibrate |
Измерить, как токенайзер провайдера считает относительно o200k, вашим ключом |
init |
Создать ctxray.config.ts и пример теста |
config |
Показать итоговый конфиг с учётом extends и значений по умолчанию |
help |
Показать справку по ctxray или по одной команде: ctxray help inspect
|
Их принимает каждая команда:
| Параметр | Значение |
|---|---|
--lang <lang> |
Язык интерфейса: en, ru. Полный порядок, в котором ctxray его выбирает, — на странице Localization
|
--ci |
Работать как в CI на любой машине: построчный вывод, репортеры CI и замороженный lockfile. ctxray включает это и сам, если задана CI, GITLAB_CI или GITHUB_ACTIONS
|
--plain |
Печатать простые строки вместо живого вывода |
--no-color |
Выключить цвета, то же, что --plain
|
-h, --help
|
Показать справку |
-v, --version
|
Показать версию |
Большинство команд принимает и --config <file>: файл конфига вместо того, который ctxray находит сам. Без флага ctxray ищет конфиг в текущей папке, а затем в родительских вплоть до корня репозитория, поэтому команды работают и из подпапки. Простые строки ctxray печатает и сам, когда вывод идёт не в терминал, в CI, при заданной NO_COLOR или при TERM=dumb. --json никогда не идёт через живой вывод.
Номера не меняются от версии к версии, так что скрипты и пайплайны могут на них опираться.
| Код | Имя | Когда |
|---|---|---|
| 0 | ok | Всё прошло |
| 1 | failed | Упал тест или проверка |
| 2 | usage | Неизвестная команда, флаг или аргумент |
| 3 | config | Конфига нет или он неверный |
| 4 | environment | Подвели харнесс, сеть или файловая система |
| 5 | internal | Ошибка в самом ctxray. Он печатает стек и ссылку, куда о ней сообщить |
| 130 | interrupted | Ctrl+C или SIGINT |
Показывает, что загружает каждый харнесс в этом репозитории: правила, скиллы, команды и MCP-серверы, у каждого — токены и причина загрузки. Команда только читает файлы и никогда не запускает харнесс. Как каждый харнесс выбирает файлы, описано на странице Harnesses.
| Параметр | Значение |
|---|---|
--harness <ids> |
ИИ-харнессы через запятую, например claude-code,codex. Иначе — харнессы из конфига или набор по умолчанию |
--cwd <dir> |
Папка, в которой стартует агент, по умолчанию текущая |
--files <paths> |
Файлы, с которыми работает агент, через запятую: правила для них тоже загрузятся |
--json |
Вывести JSON вместо текста |
--ignore-harness-differences |
Не предупреждать, если ИИ-харнессы получают разные инструкции или скиллы |
--config <file> |
Файл конфига |
Коды выхода: 0, или 2 для неизвестного харнесса или несуществующей папки. Проблемы в ваших файлах показываются предупреждениями и inspect не валят: для этого есть ctxray test.
$ ctxray inspect --harness codex --cwd app --files app/src/main/kotlin/payments/Charge.kt
…/payments · агент стартует в app
и работает с app/src/main/kotlin/payments/Charge.kt
Codex ≈ 61
Правила ≈ 24
AGENTS.md ≈ 14 always · cwd
app/AGENTS.md ≈ 10 always · cwd
Скиллы ≈ 37
android-build ≈ 11 app/.agents/skills/android-build/SKILL.md
payouts ≈ 7 .agents/skills/payouts/SKILL.md
refunds ≈ 12 .agents/skills/refunds/SKILL.md
release ≈ 7 .agents/skills/release/SKILL.md
MCP-серверы после запуска
github .codex/config.toml
jira .codex/config.toml
Системный промпт и встроенные инструменты после запуска
⚠ app/CLAUDE.md Этот файл читают только Claude Code, Cursor CLI и OpenCode, а в прогоне нет ни одного из них other-harness
⚠ app/src/main/kotlin/payments/CLAUDE.md Этот файл читают только Claude Code, Cursor CLI и OpenCode, а в прогоне нет ни одного из них other-harness
и ещё 6 проблем в других частях репозитория
≈ — локальная оценка токенайзером o200k_base
Системный промпт, встроенные инструменты и схемы MCP-инструментов ctxray посчитает, когда запустит ИИ-харнесс
У Codex нет правил по путям, поэтому Charge.kt ничего не добавляет: оба AGENTS.md загружаются, потому что лежат в цепочке от корня до app.
Запускает тесты *.ctxray.ts и собственные проверки ctxray (lint, политики, контекст) на выбранных харнессах и слоях. API тестов описан на странице Writing Tests, слои — на The Loadout Stack, вывод — на Reporters and Reports.
| Параметр | Переменная окружения | Значение |
|---|---|---|
--harness <ids> |
CTXRAY_HARNESS |
ИИ-харнессы через запятую |
--backend <name> |
CTXRAY_BACKEND |
Бэкенд модели: mock, replay, real или имя из backends в конфиге. По умолчанию mock
|
--layer <layers> |
CTXRAY_LAYER |
Слои для прогона, например L1-L3 или L3,L5
|
--filter <text> |
Запустить только тесты, в имени которых есть этот текст | |
-u, --update-snapshots
|
Записать новые и изменившиеся снапшоты loadout | |
--ignore-harness-differences |
CTXRAY_IGNORE_HARNESS_DIFFERENCES |
Не предупреждать, если ИИ-харнессы получают разные инструкции или скиллы |
--error-on-warnings |
Считать любое предупреждение L1 ошибкой | |
--frozen |
Падать, если ctxray.lock не совпадает с конфигом. Включается сам в CI и с --ci
|
|
--no-install |
Не ставить закреплённый харнесс, которого нет в кеше, а падать | |
--record |
С --backend real сохранить ответы модели кассетами для --backend replay
|
|
--base <ref> |
Ревизия для сравнения, например origin/master. В отчёт попадёт разница loadout |
|
--reporter <names> |
CTXRAY_REPORTER |
Репортеры через запятую: console, html, json, junit, allure, markdown
|
--report-lang <langs> |
CTXRAY_REPORT_LANG |
Языки HTML-отчёта через запятую или all
|
--report-dir <dir> |
Куда класть отчёты, по умолчанию .ctxray/report
|
|
--concurrency <число> |
CTXRAY_CONCURRENCY |
Сколько сессий харнесса тест L6 или L7 запускает одновременно, по умолчанию одну |
--budget <usd> |
CTXRAY_BUDGET_USD |
Сколько долларов может потратить прогон с --backend real
|
-w, --watch
|
Запускать заново после каждого изменения файлов проекта. Остановить — клавишей q
|
|
--config <file> |
Файл конфига |
Харнесс, которого нет на машине, пропускается с подсказкой ctxray harness add, если только --layer не назвал уровни, которым он нужен: тогда он падает. Флаг сильнее переменной окружения, а она сильнее конфига. Коды выхода: 0, если всё прошло, 1, если упал тест или проверка, 2 для неверного значения параметра (неизвестный репортер, язык отчёта, слой или ревизия --base, отрицательный бюджет), 4 для --backend real, когда ctxray работает офлайн. С --watch код — от последнего прогона.
ctxray test --layer L1-L3 # только файлы, харнесс не запускается
ctxray test --harness codex --filter payments
ctxray test --backend replay --reporter console,htmlПро --frozen и --no-install рассказано на странице Harnesses, про их поведение на раннере — на CI Integration.
Прогоняет L1 и L2 как есть и записывает их находки в ctxray.baseline.json в корне проекта. Закоммитьте файл: дальше ctxray test отбрасывает известные находки и падает только на новых. Так ctxray можно включить в старом репозитории, не исправляя всё сразу.
| Параметр | Значение |
|---|---|
--harness <ids> |
ИИ-харнессы через запятую |
--config <file> |
Файл конфига |
В файле нет номеров строк, поэтому находка остаётся известной, даже если вы правите текст выше неё. Код выхода 0. Подробнее про L2 — на странице Policies.
Сравнивает, что L3 предсказывает в корне проекта на другой ревизии и в рабочем дереве. Показывает правила по пути, перечисленные скиллы по имени, MCP-серверы и команды — по факту наличия.
С --file сравнивает с report.json: тем, что записал прошлый ctxray test здесь, или тем, что вы скачали из прогона CI. Каждый отчёт начиная с 0.1.1 хранит loadout, который L3 предсказал в корне для каждого харнесса прогона, и diff берёт эти харнессы, если вы не назвали другие. В отчёте 0.1.0 loadout нет: diff так и скажет и выйдет с кодом 2.
Кроме вывода в терминал diff пишет diff.json для скриптов и diff.html для людей в папку отчётов, рядом с report.json прогона тестов.
| Параметр | Значение |
|---|---|
--base <ref> |
Ревизия для сравнения, по умолчанию origin/master
|
--file <report.json> |
report.json прошлого прогона, локального или из CI, с которым сравнить вместо ревизии |
--harness <ids> |
ИИ-харнессы через запятую |
--json |
Вывести JSON вместо текста |
--report-dir <dir> |
Куда писать diff.json и diff.html, по умолчанию .ctxray/report
|
--config <file> |
Файл конфига |
Коды выхода: 0, или 2, если git не знает такой ревизии, файла нет или в нём нет loadout, или если заданы и --base, и --file.
$ ctxray diff --base HEAD --harness claude-code,codex
Относительно HEAD (399c8b5e), как предсказывает L3 в корне проекта
Claude Code ≈ 147 → ≈ 169 токенов файлов +22
~ CLAUDE.md rules +16
+ .claude/rules/states.md rules +25
+ sentry mcp
− changelog commands
Codex ≈ 40 → ≈ 40 токенов файлов ±0
Ничего не изменилось
ctxray diff --file ci-report/report.json # относительно отчёта, который прогон CI оставил артефактом+ — новая часть, − — удалённая, ~ — изменённая. У команды и MCP-сервера нет своих токенов, поэтому в их строке нет числа. ctxray test --base <ref> кладёт то же сравнение в отчёт.
Отдаёт последний отчёт из папки отчётов по адресу http://127.0.0.1:<port>/, только на вашей машине. Когда прогон тестов пишет новый report.json, каждая открытая страница обновляется. Остановить — Ctrl+C.
| Параметр | Значение |
|---|---|
--report-dir <dir> |
Куда класть отчёты, по умолчанию .ctxray/report
|
--port <port> |
Порт, по умолчанию свободный |
--open |
Открыть страницу в браузере |
--config <file> |
Файл конфига |
Коды выхода: 0, или 2, если в папке ещё нет report.json. Подробности — на странице Reporters and Reports.
Закрепляет версии харнессов в ctxray.lock и ставит их в кеш ctxray. Lockfile, кеш и source: "system" описаны на странице Harnesses.
| Подкоманда | Что делает |
|---|---|
add <id>[@range] … |
Закрепить харнессы в ctxray.lock: add codex@0.169.x claude-code
|
install |
Поставить на эту машину все харнессы из ctxray.lock
|
list |
Показать закреплённые харнессы и есть ли они на этой машине |
pack |
Собрать закреплённые сборки в один архив для install --from
|
remove <id> … |
Убрать харнессы из ctxray.lock: remove codex
|
upgrade <id> … |
Обновить закреплённый харнесс до новой версии и показать, как меняется его loadout |
| Параметр | Подкоманда | Значение |
|---|---|---|
--only <ids> |
install |
Только эти харнессы, через запятую |
--frozen |
install |
Падать, если ctxray.lock не совпадает с конфигом. Включается сам в CI и с --ci
|
--from <archive> |
install |
Поставить из архива ctxray harness pack, без registry |
-o, --output <file>
|
pack |
Файл, куда писать, по умолчанию ctxray-harnesses.tar
|
--platform <keys|all> |
pack |
Платформы для архива, например darwin-arm64,linux-x64-glibc, или all. По умолчанию — платформа этой машины |
--dry-run |
upgrade |
Показать обновление, не записывая ctxray.lock
|
--config <file> |
все | Файл конфига |
Коды выхода: 0, 2, если не назван харнесс или он неизвестен, 4, если подвели загрузка, registry или lockfile. install выходит с 4 и тогда, когда харнесс так и не нашёлся, или когда --frozen нашёл расхождение.
remove правит только ctxray.lock. Если конфиг всё ещё называет харнесс, команда об этом скажет: уберите его и там, иначе --frozen упадёт на расхождении. Сборки остаются в кеше до ctxray cache prune или ctxray cache clear.
ctxray harness add claude-code codex@0.169.x
ctxray harness install --only codex
ctxray harness pack --platform linux-x64-glibc,linux-x64-musl -o harnesses.tar
ctxray harness install --from harnesses.tar
ctxray harness upgrade claude-code --dry-run
ctxray harness remove opencode$ ctxray harness list
claude-code 2.1.325 в кеше
codex 0.169.0 в кеше
cursor-cli 2026.11.13-eacade1 (latest) в кеше
gemini-cli 0.68.0 в кеше
opencode 1.19.5 в кеше
ctxray.lock
Запускает MCP-сервер на stdin и stdout с тремя инструментами: inspect, run (ctxray test) и diff. Так агент может сам проверить, не раздувает ли его изменение контекст. Claude Code Plugin запускает его за вас.
Подключите его один раз через ctxray mcp add <агент>, дальше агент запускает его сам. В терминале ctxray mcp не ждёт, а печатает эти команды.
| Подкоманда | Что делает |
|---|---|
serve |
Отдавать инструменты через stdin и stdout. Просто ctxray mcp делает то же |
add <агент> |
Подключить ctxray к claude-code, codex, gemini-cli, opencode или cursor-cli
|
| Агент | Что делает ctxray mcp add
|
С --project
|
|---|---|---|
| Claude Code | Запускает claude mcp add --scope user ctxray -- ctxray mcp
|
Пишет .mcp.json
|
| Codex | Запускает codex mcp add ctxray -- ctxray mcp
|
Пишет .codex/config.toml
|
| Gemini CLI | Запускает gemini mcp add --scope user ctxray ctxray mcp
|
Пишет .gemini/settings.json
|
| OpenCode | Пишет ~/.config/opencode/opencode.json ($XDG_CONFIG_HOME, если задана) |
Пишет opencode.json
|
| Cursor CLI | Пишет ~/.cursor/mcp.json
|
Пишет .cursor/mcp.json
|
ctxray добавляет только свою запись, остальное в файле остаётся как было. Если в конфиге уже есть сервер с именем ctxray, ничего не меняется, так что повторный запуск безопасен. Для глобального конфига Claude Code, Codex и Gemini CLI должны быть в PATH: без них add об этом скажет, а --project работает и так. JSON-файл с комментариями ctxray не трогает и печатает запись, которую нужно добавить вручную: перезапись потеряла бы комментарии.
| Параметр | Значение |
|---|---|
--project |
С add: записать в конфиг проекта, а не в ваш |
--harness <ids> |
Харнессы, на которые смотрит вызов инструмента, если сам их не назвал, например claude-code
|
Коды выхода add: 0, если ctxray подключён сейчас или был подключён раньше, 2 для неизвестного агента, 4, если агента нет в PATH, его mcp add не сработал или в файле есть комментарии.
ctxray mcp add claude-code
ctxray mcp add cursor-cli --project
ctxray mcp --harness claude-codeПоказывает или чистит кеш харнессов, общий для всех проектов на машине. Где он лежит и как работают слои, рассказано на странице Harnesses.
| Подкоманда | Что делает |
|---|---|
dir |
Напечатать папку кеша, для шагов кеширования в CI |
ls |
Показать сборки харнессов в кеше |
prune |
Удалить сборки, которыми давно не пользовались. Закреплённые в ctxray.lock остаются |
clear |
Удалить из кеша все сборки харнессов, в том числе закреплённые |
| Параметр | Значение |
|---|---|
--older-than <days> |
Удалять сборки, которыми не пользовались столько дней, по умолчанию 30 |
--all |
Удалить все сборки, которых нет в ctxray.lock, даже свежие |
-y, --yes
|
Удалить по-настоящему. Без него clear показывает, что уйдёт, и выходит с 2 |
--config <file> |
Файл конфига |
Коды выхода: 0, или 2 для неверного числа дней и для clear без --yes. Слои кеша только для чтения ctxray не трогает.
ctxray cache dir
ctxray cache prune --older-than 7
ctxray cache clear --yesПроверяет, что нужно для L4 и выше на этой машине, и печатает каждую находку как ok (✓), информацию (·), предупреждение или ошибку. С ошибками код выхода 4, иначе 0. Без флагов команда только читает: ничего не ставит и не меняет.
ctxray doctor --fix сначала чинит безопасное: создаёт папку кеша и ставит харнессы из ctxray.lock, которых на машине нет. Потом проверяет всё заново и в разделе «Исправлено через --fix» перечисляет, что сделал и что не получилось. git, сеть, прокси, CA-сертификаты, Node и ключи --fix не трогает: находки выше говорят, что с ними сделать.
| Параметр | Значение |
|---|---|
--fix |
Исправить безопасное: создать папку кеша и поставить харнессы из ctxray.lock
|
--config <file> |
Файл конфига |
| Группа | Проверки |
|---|---|
| Система | Версия ctxray и ключ платформы. git в PATH (без него ошибка: L4 и выше копируют проект через git). Node.js в PATH (он нужен MCP-серверам на Node). Настройки, которые администратор положил в /Library/Application Support/ClaudeCode, /etc/claude-code, /etc/codex или их аналоги на Windows: их ctxray изолировать не может. На macOS — sandbox-exec. На других системах — напоминание запускать L4 и выше в контейнере |
| Сеть | Прокси со скрытыми учётными данными. HTTP_PROXY без HTTPS_PROXY. Записи NO_PROXY, которые Bun понимает не так, как curl (*.corp.com, диапазоны CIDR). Существует ли каждый файл CA и есть ли в нём сертификаты PEM. Системное хранилище сертификатов. npm registry, сертификаты CA из .npmrc и отвечает ли registry (без сети проверка пропускается) |
| Харнессы | Папка кеша, её сборки и размер, можно ли в неё писать. Слои кеша только для чтения. Lockfile и его расхождения с конфигом. Для каждого закреплённого харнесса: установлен ли он, есть ли сборка для этой платформы, есть ли нужная ему среда (node для Gemini CLI), а для source: "system" — есть ли он в PATH и та ли у него версия |
$ ctxray doctor
Система
· ctxray 0.1.0 на darwin-arm64
✓ git 2.54.0
✓ Node.js 26.13.1
✓ sandbox-exec запускает харнессы в песочнице
Сеть
· Прокси нет: запросы идут напрямую
✓ npm registry https://registry.npmjs.org/
✓ Registry отвечает (200)
Харнессы
✓ Кеш ~/Library/Caches/ctxray: 6 сборок, 1 741 МБ
✓ Lockfile ctxray.lock
✓ claude-code 2.1.325 установлен
✓ codex 0.169.0 установлен
✓ cursor-cli 2026.11.13-eacade1 установлен
✓ gemini-cli 0.68.0 установлен
✓ opencode 1.19.5 установлен
Всё, что нужно для L4 и выше, на месте
Настройки прокси, CA и registry, которые проверяет doctor, описаны на странице Enterprise.
Просит модель написать промпты для тестов L6 по описанию каждого скилла и каждого правила, которое модель выбирает по описанию: такие, что должны его выбрать, и пограничные, что не должны. Результат ложится в JSON-файл для вашего ревью, а тест читает его через corpus() (Writing Tests).
| Параметр | Значение |
|---|---|
--from-descriptions |
Писать по описанию каждого правила и скилла, которые модель выбирает по описанию. Обязателен |
--out <file> |
JSON-файл, куда писать, для corpus() в тесте. Обязателен |
--model <id> |
Модель, которая пишет, по умолчанию claude-opus-5-5: не та, что под тестом |
--count <n> |
Сколько промптов каждого вида на правило или скилл, по умолчанию 5 |
--harness <ids> |
ИИ-харнессы через запятую |
--force |
Перезаписать уже существующие файлы |
--config <file> |
Файл конфига |
Модель вызывается через ваш upstream и ваш ключ, поэтому без сети команда не работает. ctxray предупреждает, если харнесс под тестом работает на той же модели: модель, которая проверяет собственные промпты, мало что доказывает. Коды выхода: 0, 1, если для какого-то правила или скилла не получилось, 2 при нехватке параметров или существующем файле без --force, 4 в режиме офлайн.
ctxray gen-prompts --from-descriptions --out prompts/skills.json --count 8Измеряет, как токенайзер провайдера считает по сравнению с o200k, для каждого класса текста (проза, код, JSON, нелатиница, метаданные), через эндпоинт подсчёта провайдера и ваш ключ. В ctxray уже есть измеренная калибровка для Anthropic, так что команда нужна, только чтобы её проверить или измерить другую модель.
| Параметр | Значение |
|---|---|
--provider <anthropic|openai|google> |
Провайдер модели. Обязателен |
--model <id> |
Модель, которой считать. Обязателен |
--out <file> |
Записать коэффициенты в этот файл, а не выводить их |
--config <file> |
Файл конфига |
Команда отправляет около 40 запросов, поэтому офлайн тоже не работает. Коды выхода: 0, 2, если не указаны провайдер или модель, 4 в режиме офлайн или когда запрос подсчёта к провайдеру не удался.
ctxray calibrate --provider anthropic --model claude-sonnet-5-5 --out anthropic.jsonСоздаёт ctxray.config.ts с Claude Code и Codex и ctxray/loadout.ctxray.ts — тест, который проверяет, что каждый харнесс загружает свой корневой файл правил. Добавляет .ctxray/ в существующий .gitignore. Что получилось, разобрано на странице Getting Started.
| Параметр | Значение |
|---|---|
--force |
Перезаписать уже существующие файлы |
Печатает конфиг с учётом extends и значений по умолчанию, со скрытыми секретами (по встроенным шаблонам и по вашим redact.patterns) и файлы, из которых он собран. Пригодится, когда унаследованная настройка ведёт себя не так, как вы ждёте. Все ключи перечислены на странице Configuration.
| Параметр | Значение |
|---|---|
--config <file> |
Файл конфига |
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие