Tool

`watch`

You cannot improve what you cannot measure. watch launches a process with RepoQL as its OpenTelemetry collector, and everything it emits lands in tables while it is still running — alongside sampled CPU and memory for the whole process tree. Evidence you can query repeatedly, not output you read once.

The canonical thing to measure is the agent itself. Claude Code is OpenTelemetry-native — it just emits nothing until you flip its switch. You ask “what does a Claude session actually do, and what does it cost?” — so your agent runs one under watch, switch flipped.

Your agent calls — mcp

watch executable="claude" arguments=["-p", "summarize this repository in three sentences"] environment="CLAUDE_CODE_ENABLE_TELEMETRY=1;OTEL_LOG_TOOL_DETAILS=1"

You call — cli

rql watch --env "CLAUDE_CODE_ENABLE_TELEMETRY=1;OTEL_LOG_TOOL_DETAILS=1" \ -- claude -p "summarize this repository in three sentences"

What comes back — the same on both surfaces

[rql watch] run: 41634af3714742c8bc7494043505e7bb [rql watch] schema: watch [rql watch] query telemetry: SELECT * FROM watch.summary('41634af3714742c8bc7494043505e7bb'); -- payloads arriving? exited? slowest spans SELECT * FROM watch.errors('41634af3714742c8bc7494043505e7bb'); -- exceptions with innermost frames … the raw log stream and watch.surface, everything queryable RepoQL is a local-first codebase intelligence engine — conventional .NET software that makes AI agents dramatically more capable — that indexes repositories into a queryable property graph …

The last lines are Claude's own answer — the child's output passes through untouched while its telemetry lands in tables. Then you read the session back:

-- each api_request event carries that turn's tokens, cost, and latency -- (the ready-to-paste query ships at help:///tools/watch/watching-claude.md) SELECT model, input_tokens, output_tokens, round(cost_usd, 4) AS cost_usd, duration_ms … model input_tokens output_tokens cost_usd duration_ms claude-fable-5 2 414 1.3141 8287

One agent turn: 414 tokens out, $1.31, 8.3 seconds — and with OTEL_LOG_TOOL_DETAILS=1 the same tables record every tool the agent reached for, with its arguments. Session-level accounting, tool by tool, turn by turn, in SQL.

Parameters

Parameter		What it does
executable	required	A binary on the PATH, or a path to one.
arguments	optional	Arguments to pass to it.
environment	optional	Extra variables as `key=value;key2=value2`. Use it to switch on an application's own telemetry.
workingDirectory	optional	Where to run it. Defaults to the caller's directory.

What lands in the tables

Traces — spans with their timings, attributes, and parentage.
Logs — every record the process emits, with severity and structure preserved.
Metrics — whatever the application reports, as time series.
Resource use — sampled CPU and memory for the whole process tree, whether or not the application is instrumented at all.

The run's life

The call returns as soon as the process starts, with a run id and the schema to query. The run ends when the process exits. Telemetry from a finished run stays queryable — that is the point of putting it in a database rather than on a terminal.

The ask this unlocks

Measurement is not the point — the loop is. Once your agent can run your program and query what happened, you can ask for outcomes instead of observations: “run my app and make ingestion faster, without increasing memory usage.” The agent runs it under watch, reads the slow spans and the memory samples, changes the code, runs it again — and the claim “it is faster now” arrives with before-and-after numbers from the same tables, including the memory ceiling it was told not to touch.

A worked example →

This page names what exists. The depth behind every name ships inside the binary at help:///: the bounds, the failure modes, how they compose. It answers to explore and read exactly like your code does. Install it, and your agent has the manual.