Statusline & telemetry
Inspect Ratel Local events and show estimated context savings in Claude Code.
Ratel Local records local operational events as JSONL. Claude Code can use that stream to show session activity and estimated context savings in its statusline.
Ratel Core telemetry owns the event vocabulary and reliability contract. This page covers the files and commands Ratel Local operates.
What gets written
By default, ratel-mcp serve writes one JSON object per line to:
~/.ratel/telemetry/<project-slug>/<session-id>.jsonl<project-slug> is the gateway process's absolute working directory with / and .
replaced by -. Each gateway launch creates a new timestamped session file. Events cover
searches, invocations, upstream calls, authorization, and an estimate of each upstream's
tool-definition payload.
Control the sink at gateway startup:
# Exact output file
ratel-mcp serve --telemetry-file /secure/path/ratel.jsonl
# Different root for per-project buckets
RATEL_TELEMETRY_DIR=/secure/ratel-telemetry ratel-mcp serve --auto-config
# Disable it
ratel-mcp serve --telemetry off
ratel-mcp serve --no-telemetry
RATEL_TELEMETRY=off ratel-mcp serve --auto-configThe statusline discovers only the per-project bucket under ~/.ratel/telemetry, or under
RATEL_TELEMETRY_DIR when Claude Code inherits that variable. It does not discover an
arbitrary --telemetry-file.
Keep the project buckets aligned
The gateway writes to a bucket derived from its process working directory. The
statusline reads the bucket derived from Claude Code's workspace.project_dir.
If the
paths differ, the statusline says waiting for Ratel telemetry. Start the gateway from
the project root, even when you also pass --project-root.
Read the statusline
ratel-mcp statusline reads Claude Code's statusline JSON from stdin and prints two rows.
With ANSI colors removed, output resembles:
● Claude Opus 50k / 200k · 25% 10m ⎇ main
█████░░░░░░░░░░░░░ Ratel on saves ~1k (2 tools)| Part | Meaning |
|---|---|
dot and Ratel on | Claude Code has a Ratel MCP entry or enabled Ratel plugin |
| model, context, time, branch | values from Claude Code's statusline payload and current Git branch |
| bar | current context-window usage |
saves ~… | estimated upstream tool-definition tokens hidden behind Ratel |
could trim ~… | the same estimate while Ratel is not enabled in Claude Code |
The savings number is an estimate, not measured provider billing. Ratel serializes the upstream tool definitions and estimates one token per four UTF-8 bytes. Older telemetry without payload size falls back to 130 tokens per tool.
Missing telemetry prints waiting for Ratel telemetry. Malformed Claude input fails
open with loading and unavailable lines; it does not block Claude Code.
Install, replace, or remove it
ratel-mcp statusline install
ratel-mcp statusline install --force
ratel-mcp statusline uninstallInstall and uninstall confirm before writing; pass --yes to skip confirmation. Install
writes a command statusline with zero padding and a 30-second refresh interval to
~/.claude/settings.json. It refuses to replace another tool's statusline unless you pass
--force.
Uninstall removes only a Ratel-owned setting. Other Claude Code settings and statuslines
remain untouched. mcp import and mcp link also attempt installation after wiring
Claude Code; they skip an existing non-Ratel statusline.
Retention and privacy
The JSONL files stay local; this sink does not send them over the network. They can still contain search text, tool identifiers, error details, and operational metadata. Protect the telemetry directory like other agent logs and review it before sharing.
Ratel Local 0.4.0 does not prune old session files. Stop the gateway before deleting files you no longer need. Disabling the sink stops new local events; it does not delete existing files, so the statusline can continue showing the latest stored estimate.