Skip to content
Back to search

motel

A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite. Point your app's OTLP/HTTP exporters at the local motel server and debug with real runtime evidence — from a terminal, the…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kitlangton--motel/badge.svg)](/listings/kitlangton--motel)

HTML

<a href="/listings/kitlangton--motel"><img src="/api/listings/kitlangton--motel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 117 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # motel
  2. A local OpenTelemetry ingest + TUI viewer for development, backed by
  3. SQLite. Point your app's OTLP/HTTP exporters at the local motel server
  4. and debug with real runtime evidence — from a terminal, the built-in web
  5. UI, or directly from an AI coding agent.
  6. ## For agents: install the motel-debug skill
  7. `motel` ships a companion skill that teaches Claude Code, OpenCode,
  8. Cursor, Codex, and 40+ other agents how to debug with runtime evidence
  9. by querying motel's local OTLP store. Install it once and any future
  10. agent session in the project will know how to use it.
  11. ```bash
  12. # Project-local (adds to .claude/skills, .agents/skills, etc.)
  13. npx skills add kitlangton/motel --skill motel-debug
  14. # Or globally, for every project
  15. npx skills add kitlangton/motel --skill motel-debug -g
  16. ```
  17. See the full skill at [`skills/motel-debug/SKILL.md`](skills/motel-debug/SKILL.md).
  18. ## For humans: install and run the TUI
  19. motel is distributed on npm as `@kitlangton/motel`. The binary is a Bun
  20. script, so Bun must be on your `PATH` at runtime:
  21. ```bash
  22. # one-off (no install)
  23. bunx @kitlangton/motel
  24. # or install globally
  25. bun add -g @kitlangton/motel
  26. motel
  27. # npm also works (Bun still required to run it)
  28. npm install -g @kitlangton/motel
  29. ```
  30. Don't have Bun?
  31. ```bash
  32. curl -fsSL https://bun.sh/install | bash
  33. ```
  34. `motel` starts the local OTLP ingest server on
  35. `http://127.0.0.1:27686` and launches the TUI. Press `?` once inside for
  36. the keyboard cheat sheet, or `c` to copy paste-ready setup instructions
  37. for any Effect/OTEL app you want to trace.
  38. Requirements: [Bun](https://bun.sh/) v1.1 or newer.
  39. ## How your app connects
  40. Once motel is running, point your app's OTLP/HTTP exporters at these
  41. local endpoints:
  42. ```
  43. http://127.0.0.1:27686/v1/traces
  44. http://127.0.0.1:27686/v1/logs
  45. ```
  46. Motel keeps everything in a machine-global local SQLite database at
  47. `${XDG_STATE_HOME:-~/.local/state}/motel/telemetry.sqlite`. One managed
  48. daemon is shared across local projects. No Docker, no cloud account.
  49. The store retains seven days of telemetry by default and targets a 1 GB
  50. active-data ceiling using bounded background batches. Recent data is preserved while
  51. the oldest completed traces and logs are removed first. Configure the policy
  52. with `MOTEL_OTEL_RETENTION_HOURS`, `MOTEL_OTEL_MAX_DB_SIZE_MB`,
  53. `MOTEL_OTEL_RETENTION_TRACE_BATCH`, `MOTEL_OTEL_RETENTION_LOG_BATCH`, and
  54. `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`. Existing databases created without
  55. incremental auto-vacuum are never silently rewritten at startup; deleted pages
  56. are reused, but shrinking such a historical file requires an explicit offline
  57. SQLite `VACUUM` chosen by the user.
  58. ## How agents connect
  59. Agents with the `motel-debug` skill installed will automatically use
  60. motel's HTTP API. The full OpenAPI spec is at
  61. `http://127.0.0.1:27686/openapi.json` — the key endpoints are:
  62. ```
  63. GET /api/health liveness check
  64. GET /api/services services reporting telemetry
  65. GET /api/traces?service=<service> recent traces for a service
  66. GET /api/traces/<trace-id> full trace tree
  67. GET /api/spans/<span-id> single span + logs
  68. GET /api/logs?service=<service> recent logs
  69. GET /api/traces/search?... structured trace search
  70. GET /api/logs/search?... structured log search
  71. GET /api/ai/calls AI SDK call inspector
  72. ```
  73. ## TUI keys
  74. - `?` — keyboard cheat sheet
  75. - `j` / `k` or `↑` / `↓` — move selection
  76. - `enter` / `esc` — drill in / back out (trace → waterfall → span detail)
  77. - `[` / `]` — switch service
  78. - `tab` — toggle service logs
  79. - `/` — filter traces
  80. - `s` — cycle sort (recent → slowest → errors)
  81. - `t` — cycle theme
  82. - `c` — copy paste-ready setup instructions for another app
  83. - `o` — open selected trace in the browser
  84. - `q` — quit
  85. ## Privacy note
  86. motel is a local development tool, but your app can emit sensitive
  87. telemetry. Correlated logs may include secrets, tokens, or PII if your
  88. app logs them; AI call traces may include full prompt content and
  89. response text. Treat the local SQLite store as sensitive development
  90. data when pointing motel at real workloads.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.