ИИ-агенты (Claude Code, Codex, Cursor, Gemini CLI)
OxL — новый язык: модель его не знает. Агент работает хорошо, когда ему не приходится угадывать и читать файлы целиком. Для этого в oxl есть
два готовых куска:
- Сервер MCP (
oxl mcp, Model Context Protocol по stdio) — часть бинарника компилятора. Отвечает коротко и точно, из настоящего front end: диагностики с готовыми исправлениями, только упавшие тесты, сигнатуры из исходников std, один раздел Стандарта, снимок отладчика. - Навыки (Agent Skills) и
AGENTS.md— компактный учебник языка, типичные ошибки моделей (у каждой указан код диагностики), идиомы, тесты, отладка, устройство проекта. Каждый пример кода в них компилируется в CI.
Быстрый старт#
oxl ai setup # в каталоге проекта: Claude Code (.mcp.json, .claude/skills, CLAUDE.md, AGENTS.md)
oxl ai setup --all # Claude Code, Codex, Cursor, Gemini CLI
oxl ai setup --codex --cursor ./myproject
oxl ai list # что получает каждый клиентПосле настройки перезапустите агента (в Claude Code — /mcp). Повторный запуск ничего не меняет, существующие настройки сливаются с нашими
(другие MCP-серверы сохраняются). Флаги: --force, --dry-run, --link (символические ссылки на навыки вместо копий), --command C.
Инструменты сервера oxl#
Ответ — компактный текст; format: "json" есть у check, test, run, symbol, std_lookup, debug. Каждый ответ ограничен по размеру, обрезанные
списки заканчиваются строкой «…N more».
| Инструмент | Что делает |
|---|---|
check | только диагностики: файл:строка:столбец severity код: сообщение и строка fix: с исправлением компилятора; ok, если чисто. code — проверить фрагмент без файла |
build, run | сборка; запуск с args, stdin, timeout: код выхода и хвосты stdout / stderr (сообщение паники — в stderr); ошибки компиляции — компактными диагностиками |
test | строка 1 passed, 2 failed и только падения: имя, место, сообщение, строки at пользовательского кода, хвост вывода. Выбор: filter, exact, tag, kind, seed, failed |
fmt | форматирование текста (code) или файлов (path, check) |
symbol | сигнатура + документация + определение (info, def) или ссылки (refs); по line/col или по name |
std_lookup | сигнатуры и однострочная документация элементов std по имени, Type.name или регулярному выражению |
explain | страница диагностики по коду |
spec | раздел Стандарта по номеру (§7.2, III.9) или ключевому слову; lang: "ru" |
debug | неинтерактивный снимок: запуск под lldb до первой точки останова или паники; стек (только кадры OxL), локальные переменные с pretty-printers, значения expressions |
new | новый пакет |
Ресурсы: файлы share/oxl/ai доступны как oxl://ai/<путь> (resources/list, resources/read) — навыки можно прочитать и клиентом без поддержки skills.
Протокол: JSON-RPC 2.0, версия 2025-06-18 с откатом к 2025-03-26 и 2024-11-05.
Примеры размера ответа: чистый check — 2 байта, одна ошибка arg-count — 91, std_lookup push — 188, spec "§7.2" — около 1,1 КБ
(вместо файла в 237 КБ), снимок паники с стеком и локальными — около 300 байт. Список всех схем инструментов — около 8 КБ один раз за сессию.
Что записывает oxl ai setup#
| Клиент | Флаг | Сервер MCP | Навыки | Инструкции |
|---|---|---|---|---|
| Claude Code | --claude | .mcp.json | .claude/skills/ | блок в AGENTS.md и CLAUDE.md с @AGENTS.md |
| OpenAI Codex CLI | --codex | .codex/config.toml, [mcp_servers.oxl] | .agents/skills/ | блок в AGENTS.md |
| Cursor | --cursor | .cursor/mcp.json | .agents/skills/ | .cursor/rules/oxl.mdc для **/*.oxl и AGENTS.md |
| Gemini CLI | --gemini | .gemini/settings.json | .agents/skills/ | AGENTS.md (в context.fileName) |
Без флага берутся клиенты, чьи каталоги уже есть в проекте, а в пустом проекте — Claude Code. Вручную то же самое:
claude mcp add oxl -- oxl mcp
codex mcp add oxl -- oxl mcp
gemini mcp add oxl oxl mcpЛюбой другой клиент MCP: stdio-сервер с командой oxl и аргументом mcp. Плагин Claude Code лежит в share/oxl/ai/claude-plugin
(claude --plugin-dir …): навыки и .mcp.json. Соглашения клиентов взяты из их документации; CI проверяет создаваемые файлы, но не самих клиентов.
Навыки#
| Навык | Содержание |
|---|---|
oxl-language | 12 отличий от Rust / Go / TS, экран OxL, справочники: синтаксис, типы, ошибки и эффекты, владение, конкурентность, сервисы, std по задачам, ошибки моделей, идиомы |
oxl-testing | виды тестов, утверждения, фикстуры, mock, sim, fuzz, bench, снимки; запуск и чтение результата через test |
oxl-debugging | порядок от дешёвого к дорогому, чтение паник, debug, dbg, трассировка, профилировщик |
oxl-project | структура пакета, oxl.toml, workspace, профили, зависимости, команды |
Правила экономии токенов, которым учат навыки: check вместо сборки, std_lookup вместо чтения std, spec вместо чтения Стандарта, test {exact} вместо
всего набора, debug вместо отладочных print, explain вместо догадок. Подробности и устройство — в
docs/ai.md дерева исходников.
Что нужно на машине#
oxl в PATH (или полный путь в настройках клиента, oxl ai setup подставит его сам, если oxl не найден в PATH); для debug — lldb-18
(oxl doctor скажет, чего не хватает). Всё остальное (std, документация, Стандарт, навыки) сервер находит по префиксу установки.