motel skill
The motel-debug skill and a local telemetry server: the agent traces a bug through logs and spans of the running app.
- 306 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Telemetry can contain tokens, personal data and prompts, and the local database has no password.
- The agent edits code and adds temporary blocks that must be cleaned out before committing.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/motelDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Telemetry can contain tokens, personal data and prompts, and the local database has no password.
- The agent edits code and adds temporary blocks that must be cleaned out before committing.
This is third-party code. Review the repository files before installing.
What it does
motel is a local OpenTelemetry server with a terminal viewer and SQLite storage. An app sends traces and logs to it over OTLP/HTTP, and the `motel-debug` skill teaches Claude Code, Cursor, Codex and OpenCode to debug code from that data. The skill walks the agent through a loop: check that the server is running (`motel start` when it is not), write 3 to 5 hypotheses, add temporary telemetry and reproduce the failure. Every debug block is wrapped in `#region motel debug` markers and carries a `debug.hypothesis` attribute. The agent then queries spans and logs over the HTTP API, marks each hypothesis confirmed, rejected or inconclusive, and changes code only with evidence. After verification the blocks are removed with `scripts/clear-motel-debug.ts`.
Who it is for. TypeScript and Effect developers whose agent fixes bugs blind and who need traces to check its guesses.
Good fit when
- A test fails intermittently and the cause cannot be guessed from the code.
- An API request is sometimes slow and nobody knows which part of the chain loses the time.
- An Effect or OpenTelemetry app already emits spans and the agent has to see them.
- The agent proposed a blind fix and it needs runtime evidence.
- Model calls in the app are inspected through prompts, responses and token usage.
Not a fit when
- The failure is visible in the stack trace and fixed by editing one line.
- The app cannot be set up to send OTLP, for instance in a locked environment without local port access.
- The machine has no Bun and nobody plans to install it.
Example request
The payment test fails intermittently. Start motel, form hypotheses, add telemetry and show which one the traces confirm.Limitations
The server runs only under Bun 1.1 or newer, even when installed through npm. The database lives at `${XDG_STATE_HOME:-~/.local/state}/motel/telemetry.sqlite` and is shared by every local project. By default it keeps seven days of data under a ceiling of about 1 GB; the limits are changed with `MOTEL_OTEL_RETENTION_HOURS` and `MOTEL_OTEL_MAX_DB_SIZE_MB`. Logs may contain tokens and personal data, and model call traces store full prompts and responses, so treat the database as sensitive. The server listens on `127.0.0.1:27686` with no authentication. The agent leaves debug blocks in the code until the fix is confirmed, so remove them before committing.
How to disable. Stop the daemon with `motel stop`, delete the skill from the agent's skills directory and remove the `telemetry.sqlite` file. Search for `#region motel debug` blocks in code and delete them.
FAQ
How do I install motel-debug in Claude Code?
Run `npx skills add kitlangton/motel --skill motel-debug` in the project. The `-g` flag installs the skill globally for every project.
Do I need to install the motel server itself?
Yes, the skill only drives the debugging. Install the server with `bun add -g @kitlangton/motel` or run it once through `bunx @kitlangton/motel`; Bun is required on the machine.
Where does the app send telemetry?
To `http://127.0.0.1:27686/v1/traces` for traces and `http://127.0.0.1:27686/v1/logs` for logs, over OTLP/HTTP. In the terminal viewer the `c` key copies ready setup instructions for the app.
How does the agent find data for its hypothesis?
With a request like `/api/spans/search?service=<service>&attr.debug.hypothesis=<id>`: the `debug.hypothesis` attribute ties a record to a hypothesis. Logs and traces have the matching `/api/logs/search` and `/api/traces/search`.
What happens to the debug blocks after the fix?
Run `scripts/clear-motel-debug.ts`: it removes every block between `#region motel debug` and `#endregion motel debug` in JS and TS files. Without the script, delete blocks by hand and search for leftovers.
Discussion
No questions or reviews yet.
Related
SkillsSkill configures OpenTelemetry: collectors, sampling, security and telemetry from AI agents, without flooding the context.
Four OpenTelemetry skills covering application instrumentation, semantic conventions, the Collector and the OTTL language.
A skill set for website performance and scalability, currently holding ooda-loop: observe, orient, decide, act.
OpenTelemetry-based CLI tracing for Claude Code, Cursor and Codex sessions, showing what the agent actually did and what it cost
The all-deploy skill puts a site, app or API online: audit, preview, response check and rollback
A marketplace of OpenTelemetry plugins for Claude Code, Codex, Copilot and other agents that checks and follows releases itself.
README in short
The README splits installation into two paths: a skill for agents and a server with an interface for people. The terminal UI shows traces, a call waterfall and service logs, and the `o` key opens a selected trace in the browser.
README badge
Original 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?)