ask-oracle

oracle — Bun-first CLI для получения второго мнения от любой чат-модели с OpenAI-совместимым API.

Инструмент рассчитан на разработчиков и coding agents, которым нужен простой способ спросить другую модель про код, архитектуру, cleanup или доступность без полноценного агентного цикла.

Контракт у CLI намеренно минимальный:

• в stdout попадает только ответ модели
• в stderr попадает служебная информация и данные о сессии
• CLI сам не редактирует файлы
• в запрос можно подмешивать локальный кодовый контекст из файлов и директорий

Что умеет

oracle полезен, когда хочется быстро получить второе мнение без отдельной сложной интеграции.

Типичные сценарии:

• попросить модель упростить реализацию
• получить архитектурный фидбек перед рефакторингом
• продолжить обсуждение в следующем запросе через follow-up
• проверить код на доступность

Требования

Перед установкой убедитесь, что у вас есть:

• Bun в PATH
• доступ к OpenAI-совместимому API
• API-ключ, экспортированный в переменную окружения

Если вы хотите передавать директории или большой кодовый контекст, установите еще и repomix:

npm install -g repomix

Установка

Установите пакет из npm:

npm install -g ask-oracle

Пакет публикуется через npm, но сам исполняемый файл рассчитан на запуск через Bun. На практике это означает: установка идет из npm, а для работы команды нужен доступный bun.

Имя пакета в npm — ask-oracle, а исполняемая команда после установки — oracle.

Публикация из GitHub Actions

Публикация настроена через GitHub Actions и секрет репозитория NPM_TOKEN.

Для зависимостей в репозитории используется один lockfile: bun.lock. package-lock.json в проекте не хранится, а CI ставит зависимости через bun install --frozen-lockfile.

Что нужно сделать в GitHub один раз:

• открыть Settings -> Secrets and variables -> Actions
• добавить repository secret с именем NPM_TOKEN
• вставить туда npm token с правами Read and Write
• убедиться, что у токена включен обход 2FA для публикации

В репозитории уже настроены два workflow:

• .github/workflows/ci.yml: проверки на push и pull_request
• .github/workflows/publish.yml: публикация в npm при GitHub Release -> published

Релизный процесс такой:

1. Поднять версию в package.json.
2. Закоммитить изменения и запушить их в GitHub.
3. Создать git-тег вида vX.Y.Z, где X.Y.Z совпадает с версией в package.json.
4. Опубликовать GitHub Release на основе этого тега.
5. Workflow Publish to npm прогонит проверки и выполнит npm publish.

Workflow специально проверяет, что тег релиза совпадает с версией пакета. Если версия в package.json равна 0.1.1, релиз должен быть создан по тегу v0.1.1.

Быстрый старт

1. Экспортируйте API-ключ

Пример для OpenRouter:

export OPENROUTER_API_KEY=your-token

2. Пройдите интерактивную настройку

oracle config

Команда спросит три значения:

• имя env-переменной с API-ключом, например OPENROUTER_API_KEY
• базовый URL API, например https://openrouter.ai/api/v1
• модель по умолчанию, например openai/gpt-5-mini

oracle хранит имя переменной, а не сам секрет.

3. Отправьте первый запрос

oracle ask -p "Дай второе мнение по этому решению."

Базовое использование

Простой запрос

oracle ask -p "Посмотри на эту реализацию и укажи лишнюю сложность."

Запрос с файловым контекстом

oracle ask \
  -p "Посмотри на эту реализацию и предложи более чистую версию." \
  -f src/commands/ask.ts \
  -f src/context/collect.ts

Запрос с директорией

oracle ask \
  -p "Коротко объясни, как в этом проекте собирается контекст." \
  -f src/context

Если передать директорию, oracle автоматически переключится на repomix. Если repomix не установлен или недоступен в PATH, команда завершится с ошибкой.

Запрос через stdin

printf "Отдельно обрати внимание на читаемость и нейминг." | oracle ask -p "Поревьюй этот код." -f src/shared/copy.ts

Если использовать и -p, и stdin, CLI сохранит оба источника:

• -p станет основным запросом
• stdin станет дополнительными указаниями

Если -p не передан, а запрос приходит только через stdin, oracle считает этот текст основным запросом.

Запрос с изображением внутри prompt

oracle умеет распознавать image-маркеры прямо в основном prompt:

oracle ask -p "Опиши интерфейс на [image:./screenshots/home.png] и скажи, где UX слабый."

Поддерживаются два варианта источника:

• локальный путь: [image:./path/to/file.png]
• URL: [image:https://example.com/image.png]

Что делает CLI:

• заменяет маркер в тексте на видимый якорь вида [Image 1]
• прикладывает реальное изображение к user-сообщению модели в той же позиции
• дедуплицирует повторные упоминания одного и того же изображения внутри одного запроса
• завершает команду с ошибкой, если изображение нельзя прочитать, скачать, распознать или сохранить в сессию

Image-маркеры обрабатываются только в основном prompt. Они не парсятся во файловом контексте -f и не парсятся в stdin, если основной prompt уже был передан через -p.

Переопределение модели

oracle ask \
  --model anthropic/claude-sonnet-4.5 \
  -p "Оспорь мои предположения в этом дизайне." \
  -f src/cli/router.ts

Пресеты

Сейчас в oracle есть два встроенных пресета.

cleanup

Используйте, когда хотите упростить код без изменения поведения.

oracle ask \
  --preset cleanup \
  -f src/commands/ask.ts

Если пресет уже задает направление запроса, -p можно не передавать. Добавляйте его только когда нужно сузить или уточнить задачу для модели.

a11y

Используйте, когда нужен обзор с фокусом на доступность.

oracle ask \
  --preset a11y \
  -p "Проверь этот UI-код на требования доступности." \
  -f app/components/button.tsx

Сессии и follow-up

Каждый успешный вызов oracle ask сохраняет локальную сессию и печатает ее данные в stderr.

Пример:

Сессия: 7c5d4f6f-... slug=cleanup-review

Можно сразу добавить человекочитаемую метку через --slug:

oracle ask \
  --slug cleanup-review \
  -p "Посмотри на этот рефакторинг." \
  -f src/commands/ask.ts

Позже ту же сессию можно продолжить через --followup, используя либо id, либо slug:

oracle ask \
  --followup cleanup-review \
  -p "Переоцени предыдущий совет с учетом последних изменений." \
  -f src/commands/config.ts

При follow-up CLI поднимет предыдущую историю разговора и объединит старые источники контекста с новыми -f, если вы их передали.

Если в прошлых user-turn были изображения, oracle восстановит их из локальных snapshot-файлов в ~/.oracle/sessions/... и повторно передаст модели как мультимодальный контент. Это делает follow-up детерминированным: старые URL и исходные локальные пути не нужны для воспроизведения истории.

Как собирается контекст

oracle сам выбирает режим упаковки контекста:

• none: файлы не передавались
• raw: небольшой набор обычных файлов встраивается прямо в prompt
• repomix: директории, больше 6 файлов или больше 128 КБ суммарного объема

В raw-режиме файлы выглядят так:

<file path="src/example.ts">
...
</file>

В repomix-режиме CLI запускает repomix --stdout --style xml --include ....

Команды

oracle help

Показать общую справку.

oracle help

oracle config

Создать или обновить локальный пользовательский конфиг.

oracle config

oracle ask

Отправить запрос в настроенный провайдер.

oracle ask [опции]

Доступные опции:

• -p, --prompt <текст>: основной текст запроса, опционален если задан --preset
• -f, --file <путь>: файл или директория для контекста, можно повторять
• --preset <имя>: имя пресета
• --model <имя>: переопределить модель из конфига
• --followup <ref>: продолжить предыдущую сессию по id или slug
• --slug <текст>: человекочитаемая метка сессии
• -h, --help: показать справку

Локальное хранение данных

oracle хранит локальные данные в ~/.oracle:

• config.json: пользовательский конфиг с apiKeyEnv, baseURL и defaultModel
• sessions/*.json: история сессий
• slugs.json: отображение slug -> session id

Вывод и коды выхода

Поведение вывода специально сделано простым:

• ответ модели идет в stdout
• данные о сессии и операционные сообщения идут в stderr

За счет этого CLI удобно использовать в скриптах и агентных пайплайнах, которым нужно забрать только итоговый текст.

Коды выхода сгруппированы по типу ошибки:

• 0: успех
• 2: ошибка использования
• 3: ошибка конфига
• 4: ошибка сборки контекста
• 5: ошибка запроса к модели
• 6: ошибка сессии
• 10: непредвиденная внутренняя ошибка

Troubleshooting

Oracle еще не настроен

Запустите:

oracle config

Переменная окружения "..." не задана или пуста

Экспортируйте API-ключ в ту переменную окружения, имя которой сохранено в конфиге, и повторите команду.

Нужен repomix, но его нет

Установите его глобально:

npm install -g repomix

bun: command not found

Установите Bun и убедитесь, что он доступен в PATH. Пакет распространяется через npm, но исполняется через Bun.

Разработка

Установите зависимости:

bun install

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

bun run typecheck
bun run test

Запустите CLI локально:

bun run ./src/bin/oracle.ts help

Примечания

• oracle работает с любым OpenAI-совместимым API, а не только с OpenRouter.