Statusline & local telemetry

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.

This local sink is separate from the default-off experimental Cloud telemetry feature. Local JSONL does not enable Cloud export.

Ratel SDK telemetry owns the event vocabulary and reliability contract. This page covers the files and commands Ratel Local operates.

What gets written

By default, each Ratel Local gateway generation 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-local serve --telemetry-file /secure/path/ratel.jsonl

# Different root for per-project buckets
RATEL_TELEMETRY_DIR=/secure/ratel-telemetry ratel-local serve --auto-config

# Disable it
ratel-local serve --telemetry off
ratel-local serve --no-telemetry
RATEL_TELEMETRY=off ratel-local serve --auto-config

The 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.

Read the statusline

ratel-local 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)

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-local statusline install
ratel-local statusline install --force
ratel-local statusline uninstall

Install 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.

After a successful Claude Code import, the interactive flow offers statusline setup as a separate skippable step. import --yes installs a missing statusline but leaves another tool's statusline unchanged. link never installs it.

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 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.

Next steps