Skip to content

Getting Started RU

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

English version

ctxray — один исполняемый файл, никакой среды выполнения ставить не нужно. Выберите канал, которым уже пользуетесь, а потом пройдите первую сессию на своём репозитории.

Установка

npm

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

Homebrew

На macOS и Linux:

brew install mairwunnx/tap/ctxray

Scoop

На 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 sh

Alpine и другие системы на 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: она работает быстрее.

Docker

На 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        # macOS

Workflow релиза подписывает 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. С вашим репозиторием всё работает так же.

1. Посмотрите, что загружают агенты

Запустите inspect в корне проекта:

ctxray inspect

ctxray читает файлы каждого харнесса и показывает, что каждый из них загружает, ни один не запуская. Добавьте --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.

2. Создайте конфиг и тест

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.

3. Запустите тесты

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, сеть и кеш.

4. Закрепите харнессы и закоммитьте ctxray.lock

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.

5. Запустите в CI

В CI или с --ci ctxray сам включает --frozen: если лок-файл не совпадает с конфигом, прогон падает. Дальше подключите GitHub Action или шаблон GitLab, как показано на странице CI Integration.

Clone this wiki locally