Repository navigation
Getting Started RU
ctxray — один исполняемый файл, никакой среды выполнения ставить не нужно. Выберите канал, которым уже пользуетесь, а потом пройдите первую сессию на своём репозитории.
npm install -g @mairwunnx/ctxrayИли запустите разово, без установки:
npx @mairwunnx/ctxray inspect
bunx @mairwunnx/ctxray inspectВ пакете @mairwunnx/ctxray лежат небольшой лаунчер ctxray и типы для редактора. Сам исполняемый файл приходит в платформенном пакете, по одному на систему, — так же поставляются esbuild и Biome. npm ставит только тот пакет, чьи os, cpu и libc совпадают с вашей машиной.
| Платформенный пакет | Для чего |
|---|---|
@mairwunnx/ctxray-linux-x64, @mairwunnx/ctxray-linux-arm64
|
Linux с glibc |
@mairwunnx/ctxray-linux-x64-musl, @mairwunnx/ctxray-linux-arm64-musl
|
Alpine и другие системы на musl |
@mairwunnx/ctxray-darwin-arm64, @mairwunnx/ctxray-darwin-x64
|
macOS |
@mairwunnx/ctxray-windows-x64, @mairwunnx/ctxray-windows-arm64
|
Windows |
Лаунчер работает на Node или Bun и передаёт управление исполняемому файлу. Если он пишет, что npm не поставил исполняемый файл для вашей платформы, скорее всего, установка шла с --omit=optional: переустановите без этого флага. Если он предупреждает, что версии лаунчера и исполняемого файла разные, переустановите пакет, чтобы они совпали.
Чтобы редактор видел типы в ctxray.config.ts и тестах, добавьте пакет и в проект. Запускать тесты ctxray умеет и без этого.
npm install -D @mairwunnx/ctxrayНа macOS и Linux:
brew install mairwunnx/tap/ctxrayНа Windows:
scoop bucket add mairwunnx https://github.com/MairwunNx/scoop-bucket
scoop install mairwunnx/ctxrayНа macOS и Linux:
curl -fsSL https://github.com/MairwunNx/ctxray/releases/latest/download/install.sh | shНа Windows, в PowerShell:
irm https://github.com/MairwunNx/ctxray/releases/latest/download/install.ps1 | iexОба скрипта выбирают сборку под вашу систему, скачивают её вместе с SHA256SUMS и отказываются ставить файл, если контрольная сумма не совпала. install.sh кладёт ctxray в ~/.local/bin и подсказывает, если этой папки нет в PATH. install.ps1 кладёт ctxray.exe в %LOCALAPPDATA%\Programs\ctxray и добавляет её в пользовательский PATH, так что после установки откройте новый терминал.
Поведение скриптов меняют переменные окружения:
| Переменная | Что делает | По умолчанию |
|---|---|---|
CTXRAY_VERSION |
Ставит эту версию, например 0.1.0
|
последний релиз |
CTXRAY_DOWNLOAD_BASE |
Скачивает с зеркала, а не с GitHub. Зеркало повторяет раскладку GitHub: <base>/latest/download/<asset> и <base>/download/v<version>/<asset>
|
https://github.com/MairwunNx/ctxray/releases |
CTXRAY_INSTALL_DIR |
Куда положить исполняемый файл |
~/.local/bin, на Windows — %LOCALAPPDATA%\Programs\ctxray
|
CTXRAY_LANG |
Язык сообщений скрипта, en или ru
|
язык системы |
curl -fsSL https://github.com/MairwunNx/ctxray/releases/latest/download/install.sh \
| CTXRAY_VERSION=0.1.0 CTXRAY_INSTALL_DIR=/usr/local/bin shAlpine и другие системы на musl. install.sh сам выбирает сборку для musl. Она слинкована с libstdc++ и libgcc, которых в Alpine нет, поэтому сначала поставьте их:
apk add libstdc++ libgccБез них скрипт всё равно установит ctxray и подскажет, чего не хватает.
Старые процессоры x64. Обычной сборке для Linux x64 нужен AVX2. На машине с Linux x64 без него install.sh берёт ctxray-linux-x64-baseline.tar.gz. npm и Homebrew такую машину не отличают, так что там используйте скрипт или архив из релиза.
На macOS под Rosetta скрипт ставит родную сборку для Apple silicon: она работает быстрее.
На ghcr.io/mairwunnx/ctxray лежат два образа, для linux/amd64 и linux/arm64:
| Тег | Что внутри | Для чего |
|---|---|---|
latest, <version>
|
только исполняемый файл, на distroless |
ctxray inspect и слои L1–L3 |
runtime, <version>-runtime
|
плюс git и Node | слои L4 и выше, которые запускают харнессы |
Смонтируйте проект в /work, рабочую папку образов:
docker run --rm -v "$PWD:/work" ghcr.io/mairwunnx/ctxray inspect
docker run --rm -v "$PWD:/work" ghcr.io/mairwunnx/ctxray:runtime testСами харнессы в образах не лежат никогда: ctxray ставит те, что закреплены в вашем ctxray.lock. Как собрать с ними свой образ для CI, описано на странице CI Integration.
В каждом релизе есть архив под каждую платформу: ctxray-<platform>.tar.gz, на Windows — .zip. Версии в именах нет, поэтому releases/latest/download/<asset> всегда ведёт на самый новый.
| Платформа | Архив |
|---|---|
| Linux x64, arm64 (glibc) |
ctxray-linux-x64.tar.gz, ctxray-linux-arm64.tar.gz
|
| Linux x64 без AVX2 | ctxray-linux-x64-baseline.tar.gz |
| Linux на musl |
ctxray-linux-x64-musl.tar.gz, ctxray-linux-arm64-musl.tar.gz
|
| macOS |
ctxray-darwin-arm64.tar.gz, ctxray-darwin-x64.tar.gz
|
| Windows |
ctxray-windows-x64.zip, ctxray-windows-arm64.zip
|
Архив — полный офлайн-комплект. Рядом с исполняемым файлом в нём лежат JSON Schema в schemas/, шаблон GitLab ctxray.gitlab-ci.yml, harnesses.Dockerfile и плагин для Claude Code ctxray-claude-plugin.zip. Перенесите один архив в закрытый контур, и у вас будет всё, что поставляет ctxray. Как перенести туда харнессы, рассказывает ctxray harness pack на странице Enterprise.
tar -xzf ctxray-linux-x64.tar.gz
./ctxray --versionВ каждом релизе есть SHA256SUMS с SHA-256 всех файлов. Сверьте с ним то, что скачали:
sha256sum --check --ignore-missing SHA256SUMS # Linux
shasum -a 256 --check --ignore-missing SHA256SUMS # macOSWorkflow релиза подписывает SHA256SUMS через Sigstore, без ключей. Подпись лежит рядом, в SHA256SUMS.sigstore.json. Проверьте её через cosign, и вы будете знать, что контрольные суммы пришли из релизной сборки самого ctxray:
cosign verify-blob SHA256SUMS \
--bundle SHA256SUMS.sigstore.json \
--certificate-identity-regexp '^https://github.com/MairwunNx/ctxray/\.github/workflows/release\.yml@' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comК каждому файлу релиза GitHub ещё и прикладывает аттестацию происхождения сборки. GitHub CLI проверяет её файл за файлом:
gh attestation verify ctxray-linux-x64.tar.gz --repo MairwunNx/ctxrayЕщё в релизе лежит ctxray.cdx.json — SBOM в формате CycloneDX с зависимостями, которые вшиты в исполняемый файл.
ctxray работает на macOS, Linux и Windows, на x64 и arm64. Ему нужен 1 ГБ памяти: этого с запасом хватает на все слои и все харнессы. Меньше всего, на чём он ещё работает, — 768 МБ, а без Gemini CLI — 512 МБ.
| Что запускается | Память | Время |
|---|---|---|
inspect и test L1–L3 для Claude Code, небольшой проект |
110 МБ | 0,1 с |
| То же для всех пяти харнессов | 380 МБ | 0,4 с |
| Все пять харнессов на монорепозитории из 87 000 файлов | 620 МБ | 5 с |
Дороже всех Gemini CLI: ctxray считает его токены словарём Gemma, и загрузка словаря занимает около 300 МБ. Остальные харнессы считаются через o200k, а ему хватает нескольких мегабайт.
L4–L7 запускают сам харнесс, и его память прибавляется к памяти ctxray:
| Харнесс | Одна сессия | На диске в кеше |
|---|---|---|
| Claude Code | 300 МБ | 280 МБ |
| Codex | 180 МБ | 420 МБ |
| Gemini CLI | 230 МБ | 100 МБ |
| OpenCode | 560 МБ | 200 МБ |
| Cursor CLI | 530 МБ | 400 МБ |
ctxray запускает по одной сессии. Тест L6 или L7 с concurrency больше 1 запускает несколько сразу, и каждая лишняя добавляет сессию из таблицы: concurrency: 4 с OpenCode просит около 2,5 ГБ.
Исполняемый файл занимает на диске 130 МБ. Числа — пиковая память каждого процесса на Linux arm64 в Docker, минимумы проверены через docker run --memory. На macOS числа отличаются на несколько десятков мегабайт. Windows пока не замерен.
Шаги ниже выполнены на примере payments из фикстур самого ctxray: это проект на Kotlin с правилами, скиллами и MCP-серверами для Claude Code, Codex, Gemini CLI, OpenCode и Cursor. С вашим репозиторием всё работает так же.
Запустите inspect в корне проекта:
ctxray inspectctxray читает файлы каждого харнесса и показывает, что каждый из них загружает, ни один не запуская. Добавьте --files, чтобы указать, с какими файлами работает агент, — тогда загрузятся и правила для них:
ctxray inspect --harness claude-code --files app/src/main/kotlin/payments/Charge.kt ~/payments · агент стартует в .
и работает с app/src/main/kotlin/payments/Charge.kt
Claude Code ≈ 286
Правила ≈ 219
CLAUDE.md ≈ 63 always · cwd
AGENTS.md ≈ 23 always · import:CLAUDE.md
.claude/rules/style.md ≈ 12 always
app/CLAUDE.md ≈ 23 path · nested:app/src/main/kotlin/payments/Charge.kt
.claude/rules/payments.md ≈ 15 path · glob:**/payments/**/*.kt
…
Скиллы ≈ 48
refunds ≈ 19 .claude/skills/refunds/SKILL.md
android-build ≈ 18 app/.claude/skills/android-build/SKILL.md
…
Команды ≈ 19
changelog .claude/commands/changelog.md
MCP-серверы после запуска
github .mcp.json
jira .mcp.json
Системный промпт и встроенные инструменты после запуска
⚠ .claude/rules/web.md Ни один файл репозитория не подходит под frontend/**/*.tsx, правило никогда не загрузится dead-rule
≈ — локальная оценка токенайзером o200k_base+calibrated:claude-sonnet-5-5
Системный промпт, встроенные инструменты и схемы MCP-инструментов ctxray посчитает, когда запустит ИИ-харнесс
Как это читать:
- ≈ и числа. У каждого куска свои токены. ctxray считает их локально, поэтому это оценки, и они помечены ≈. Внизу указан токенайзер, которым они посчитаны. Подробнее о подсчёте — на странице Concepts.
-
Активация и причина. Последняя колонка правила говорит, когда оно загружается и почему загрузилось сейчас.
always · cwdгрузится в каждой сессии, начатой здесь.path · nested:…загрузилось, потому что агент работает с файлом ниже этой папки,path · glob:…— потому что файл подошёл под glob правила,import:CLAUDE.md— потому что его импортируетCLAUDE.md. Безусловное правило из.claude/rulesпоказывает простоalways. Все виды и причины перечислены на странице Concepts. - Скиллы и команды показывают, откуда они взялись. Токены скилла — это то, что модель видит в списке скиллов: имя и описание, а не всё тело.
- после запуска. По файлам нельзя узнать, сколько стоят инструменты MCP-сервера и какой длины собственный системный промпт харнесса. ctxray посчитает это, когда запустит харнесс, на слое L4.
-
Предупреждения. Строка с ⚠ называет файл, объясняет, что не так, и заканчивается id проверки, здесь
dead-rule. По этому id проверку можно ослабить или выключить в Configuration.
Без --harness вы увидите ещё и предупреждения harness-differences, например «Codex не читает этот файл, и такого текста нет ни в одном файле, который он читает, поэтому ИИ-харнессы получают разные инструкции». Что они значат, объясняет страница Concepts.
ctxray init ✓ создан ctxray.config.ts
✓ создан ctxray/loadout.ctxray.ts
Дальше: опишите настройку агента в ctxray/loadout.ctxray.ts и запустите ctxray test
ctxray.config.ts называет харнессы, которые нужно тестировать, для начала Claude Code и Codex:
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
harnesses: {
"claude-code": {},
codex: {},
},
});ctxray/loadout.ctxray.ts проверяет, что каждый харнесс загружает свой корневой файл правил:
import { expect, suite, test } from "@mairwunnx/ctxray";
// The root rules file each harness reads.
const rootRules: Record<string, string> = { "claude-code": "CLAUDE.md", codex: "AGENTS.md" };
suite("loadout", () => {
test.resolve("the root rules file loads for every file", async ({ harness, resolve }) => {
const loadout = await resolve({ files: ["README.md"] });
expect(loadout.rules).toInclude(rootRules[harness]);
});
});init не перезаписывает существующие файлы, если не передать --force. Если в проекте есть .gitignore, init добавит в него .ctxray/: туда попадают отчёты и трейсы. Все ключи конфига описаны в Configuration, API тестов — в Writing Tests.
ctxray test ctxray 0.1.0 · 2 харнесса · бэкенд: mock
проверки ctxray
L1 lint файлы проекта
claude-code ✓ 1 предупреждение codex ✓ 7 предупреждений
L4 assemble стартовый контекст
claude-code ✓ ≈ 17 030 токенов codex ○ в PATH нет codex
loadout
L3 resolve the root rules file loads for every file
claude-code ✓ codex ✓
⚠ claude-code › L1 lint › файлы проекта
.claude/rules/web.md Ни один файл репозитория не подходит под frontend/**/*.tsx, правило никогда не загрузится dead-rule
…
Слои L1 ✓ 2 L3 ✓ 2 L4 ✓ 1
Итого пройдено: 5 · пропущено: 1 · 1,5 с
Рядом с вашими тестами ctxray запускает свои проверки. L1 проверяет файлы каждого харнесса, а L4 запускает каждый харнесс с mock-моделью и измеряет контекст, с которым он на самом деле стартует. Этот запуск ничего не стоит: к модели никто не обращается. Ваш тест прошёл на L3, который только читает файлы. Каждый слой разобран на странице The Loadout Stack.
Codex на L4 пропущен, потому что на этой машине нет codex в PATH. Следующий шаг это исправит. Перед L4 полезно запустить ctxray doctor: он проверит git, сеть и кеш.
ctxray harness add claude-code codex ✓ claude-code 2.1.311 (stable) добавлен
✓ codex 0.169.0 (latest) добавлен
Записан ctxray.lock
ctxray.lock хранит точную версию каждого харнесса и контрольную сумму его сборки для каждой платформы. Закреплённый харнесс ctxray ставит в свой кеш при первом использовании, так что на вашей машине и в CI работают одни и те же сборки. Запустите ctxray test ещё раз, и Codex тоже пройдёт L4:
L4 assemble стартовый контекст
claude-code ✓ ≈ 17 030 токенов codex ✓ ≈ 8 227 токенов
Закоммитьте конфиг, лок-файл и тесты:
git add ctxray.config.ts ctxray.lock ctxray/
git commit -m "test: check what the agents load"Про harness install, upgrade и кеш рассказывает страница Harnesses.
В CI или с --ci ctxray сам включает --frozen: если лок-файл не совпадает с конфигом, прогон падает. Дальше подключите GitHub Action или шаблон GitLab, как показано на странице CI Integration.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие