motel — скилл
Скилл motel-debug и локальный сервер телеметрии: агент ищет причину бага по трассам и логам запущенного приложения.
- 306 ★ репозитория
- Последний коммит
- MIT
Расширенный доступ
Почему такой уровень
- Телеметрия может содержать токены, персональные данные и промпты, а локальная база не защищена паролем.
- Агент правит код и добавляет в него временные блоки, которые нужно вычистить перед коммитом.
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add skills/motelОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Телеметрия может содержать токены, персональные данные и промпты, а локальная база не защищена паролем.
- Агент правит код и добавляет в него временные блоки, которые нужно вычистить перед коммитом.
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
motel — локальный сервер OpenTelemetry с просмотрщиком в терминале и хранилищем SQLite. К нему приложение отправляет трассы и логи по OTLP/HTTP, а скилл `motel-debug` учит Claude Code, Cursor, Codex и OpenCode отлаживать код по этим данным. Скилл ведет агента по циклу: проверить, что сервер запущен (при необходимости `motel start`), записать 3–5 гипотез, добавить временную телеметрию и воспроизвести ошибку. Каждый блок отладки обернут в маркеры `#region motel debug` и получает атрибут `debug.hypothesis`. Затем агент запрашивает спаны и логи по HTTP API, помечает каждую гипотезу как подтвержденную, отвергнутую или неопределенную и правит код только при наличии доказательств. После проверки блоки удаляются скриптом `scripts/clear-motel-debug.ts`.
Для кого. Разработчикам на TypeScript и Effect, у которых агент чинит баги вслепую и нужны трассы, чтобы проверять его догадки.
Подходит, если
- Тест падает через раз, и по коду причину не угадать.
- Запрос к API иногда отвечает медленно, а в какой части цепочки теряется время, неизвестно.
- Приложение на Effect или OpenTelemetry уже шлет спаны, и их надо показать агенту.
- Агент предложил правку наугад, и к ней нужны доказательства из рантайма.
- Вызовы моделей в приложении разбирают по промптам, ответам и расходу токенов.
Не подходит, если
- Ошибка видна в стеке вызовов и лечится правкой одной строки.
- Приложение нельзя настроить на отправку OTLP, например в закрытой среде без доступа к локальному порту.
- На машине нет Bun, а ставить его не собираются.
Пример запроса к агенту
Тест на оплату падает через раз. Запусти motel, выдвини гипотезы, добавь телеметрию и покажи, какая гипотеза подтвердилась по трассам.Ограничения
Сервер запускается только под Bun версии 1.1 или новее, даже при установке через npm. База лежит в `${XDG_STATE_HOME:-~/.local/state}/motel/telemetry.sqlite` и общая для всех локальных проектов. По умолчанию хранится семь суток данных при потолке около 1 ГБ, пределы меняют переменные `MOTEL_OTEL_RETENTION_HOURS` и `MOTEL_OTEL_MAX_DB_SIZE_MB`. Логи могут содержать токены и персональные данные, а трассы вызовов моделей хранят промпты и ответы целиком: базу считают чувствительной. Сервер слушает адрес `127.0.0.1:27686` без авторизации. Отладочные блоки агент оставляет в коде до подтверждения исправления, поэтому перед коммитом их убирают.
Как отключить. Остановите демон командой `motel stop`, удалите скилл из каталога скиллов агента и файл `telemetry.sqlite`. Блоки `#region motel debug` в коде найдите поиском и удалите.
Частые вопросы
Как поставить motel-debug в Claude Code?
Выполните `npx skills add kitlangton/motel --skill motel-debug` в проекте. Ключ `-g` ставит скилл глобально, для всех проектов.
Нужно ли ставить сам сервер motel?
Да, скилл только ведет отладку. Сервер ставят командой `bun add -g @kitlangton/motel` или запускают разово через `bunx @kitlangton/motel`, на машине нужен Bun.
Куда приложению отправлять телеметрию?
На `http://127.0.0.1:27686/v1/traces` для трасс и `http://127.0.0.1:27686/v1/logs` для логов, по OTLP/HTTP. В терминальном просмотрщике клавиша `c` копирует готовую инструкцию для настройки приложения.
Как агент ищет данные по своей гипотезе?
Запросом вида `/api/spans/search?service=<сервис>&attr.debug.hypothesis=<id>`: атрибут `debug.hypothesis` связывает запись с гипотезой. Для логов и трасс есть аналогичные `/api/logs/search` и `/api/traces/search`.
Что делать с отладочными блоками после исправления?
Запустить `scripts/clear-motel-debug.ts`: он удаляет все блоки между `#region motel debug` и `#endregion motel debug` в файлах JS и TS. Без скрипта блоки убирают вручную и ищут остатки поиском.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
СкиллыСкилл настраивает OpenTelemetry: коллектор, выборку, безопасность и поток телеметрии из ИИ-агентов, не засоряя контекст.
Четыре скилла по OpenTelemetry: инструментирование приложений, семантические конвенции, Collector и язык OTTL.
Скиллы по производительности и масштабированию сайтов, пока один: ooda-loop, цикл наблюдения, вывода, решения и действия.
CLI-трассировка сессий Claude Code, Cursor и Codex через OpenTelemetry: что агент реально делал и сколько это стоило
Скилл all-deploy выкладывает сайт, приложение или API в интернет: аудит, превью, проверка ответа и откат
Маркетплейс плагинов OpenTelemetry для Claude Code, Codex, Copilot и других агентов: репозиторий сам проверяет и ведет релизы.
Коротко о README
README делит установку на два пути: скилл для агентов и сервер с интерфейсом для людей. Интерфейс в терминале показывает трассы, водопад вызовов и логи сервиса, а браузер открывает выбранную трассу клавишей `o`.
Бейдж для README
Исходный SKILL.md
---
name: motel-debug
description: Debug applications with motel, a local OpenTelemetry ingest and query server. Use when the user wants runtime-evidence debugging with traces or logs, wants temporary debug instrumentation that can be removed later, or needs a repo wired to send OTLP/HTTP telemetry to a local motel server. If the target repo uses Effect or @effect/*, also read references/effect.md.
---
# Motel Debug
You are in **debug mode**. Debug with runtime evidence, not guesswork.
Agents guess based on code alone. You need actual runtime data. Motel is the local OpenTelemetry server that collects traces and logs — use it as your evidence loop.
Default local server details:
- Base URL: `http://127.0.0.1:27686`
- OTLP traces: `POST /v1/traces`
- OTLP logs: `POST /v1/logs`
- Query API: `GET /api/*`
- OpenAPI: `GET /openapi.json`
- Header: `Content-Type: application/json`
- Auth: none by default
If the user provides a different motel URL, use that instead of the default.
## Workflow
### 1. Verify motel is running — and start it if not
Check `GET /api/health`. If it returns 200, continue.
If it fails (connection refused, timeout, non-200), motel isn't running.
Start it as a background daemon — **do not** launch the TUI, which is
interactive and will block your shell:
```bash
motel start
```
`motel start` ensures the machine-global managed daemon is running, writes
runtime files under `${XDG_STATE_HOME:-~/.local/state}/motel/`, and returns a
JSON status blob. It is idempotent and shared across local projects. If motel isn't on `PATH`, fall
back to `bunx @kitlangton/motel start`.
After starting, re-check `GET /api/health` (may take 1–2s to become
ready). If it still fails, read `${XDG_STATE_HOME:-~/.local/state}/motel/daemon.log` for the error
and surface it to the user.
Other lifecycle commands, for reference:
```bash
motel status # JSON status (running? pid? originating workdir?)