CLI & coding agents

Install & upgrade

npx @glassray/coach start needs no install. For a permanent glassray-coach command:

npm i -g @glassray/coach          # install (Node ≥ 20.6)
npm i -g @glassray/coach@latest   # upgrade - the CLI's ▲ notice tells you when
npm rm -g @glassray/coach         # uninstall

nvm users: global installs are per Node version - after nvm use on another version, reinstall (or install onto a system Node, e.g. Homebrew’s, to keep it everywhere). EACCES on install? Don’t sudo - point npm at a user prefix once: npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH.

Installing is not the same as running: glassray-coach start runs the server in a foreground terminal - there’s no background service.

Server commands

Command	What it does
`glassray-coach start`	Start the server + dashboard. On a fresh store, in an interactive terminal, it offers the setup menu: run Claude Code headlessly on the onboarding prompt (git writes hard-blocked), copy the prompt, or show the manual OTLP wiring. Flags: `--port` (default `5899`), `--data-dir`, `--no-open`.
`glassray-coach init`	Install the agent skill into the current repo - `./.agents/skills/` (the open Agent Skills standard: Codex, VS Code, Copilot) + `./.claude/skills/` (Claude Code); `--force` overwrites a modified copy.
`glassray-coach status`	Show the data directory and probe whether a Coach is answering on the port.
`glassray-coach doctor`	Check Node version, port availability, and data-dir writability - with one-line fixes.
`glassray-coach reset --yes`	Wipe the local data directory (asks to confirm without `--yes`).
`glassray-coach` / `glassray-coach help`	The branded landing screen: server status, every command, guide links. `glassray-coach help <command>` (or `<command> --help`) prints a data command’s own usage block.
`glassray-coach --version`	Print the CLI version.

glassray-coach mcp was removed in 0.2 - the CLI below is now the one agent surface. If you had it registered: claude mcp remove glassray, then glassray-coach init.

Data commands

Everything the dashboard can do, scriptable - and consumed by coding agents. The contract: stdout is the API’s JSON verbatim, human messages go to stderr, and exit codes are 0 (ok), 1 (API error), 2 (no Coach running). Run-starting verbs block and poll the run to completion (--no-wait to skip, --timeout <s> to bound); all take --port.

Command	What it does
`glassray-coach traces list [--q --agent --status --flow --limit --offset]`	List traces, filterable down to one flow’s members.
`glassray-coach traces get <id>`	One trace’s full span-tree view.
`glassray-coach traces tail`	Live stream of ingested trace ids, one JSON object per line.
`glassray-coach stats` / `glassray-coach usage`	Store rollups / Coach’s own LLM spend vs. budget.
`glassray-coach flows list · get · create · update · delete · audit`	Durable flow CRUD - see the worked loop. `create` takes `--name`, `--selector '<json>'` and/or `--rule` (+ `--classify selector\|llm`).
`glassray-coach flows discover [--code-root <path>]`	Read your agent’s own source (the `--code-root`, or `codeRoot:` in `glassray.yaml`) and propose flows inferred from it - name-deduped, so it only ever adds.
`glassray-coach evals list · get · create · update · run · delete`	Flow-scoped evals; either `create --deviation <id> [--flow <id>]` (promote a deviation) or `create --name <s> --text <s> [--flow <id>] [--threshold <0..1>] [--autorun-threshold <n>]` (author a rule); `run` prints the verdicts.
`glassray-coach deviations list · get · discover · resolve`	Discovery output and the resolve step of the loop.
`glassray-coach deviations discover [--sample --flow]`	Deviation discovery from traces - clusters recurring failures, optionally scoped to a flow’s members. (`discovery run` is a kept alias.)
`glassray-coach experiments list · get`	Read-only inspect of A/B experiments: `list [--flow <id>]`, `get <id>` (JSON verbatim).
`glassray-coach fix <deviationId>`	Generate the fix doc; prints the deviation with its `fixMarkdown`.
`glassray-coach runs list · get · cancel`	Inspect and cancel background runs (`queued → running → done\|error`).

Loop verbs (harness & CI)

These verbs drive glassray.yaml - the portable artifact that holds your flows (rules + selectors), run recipes (run.command), and code root (codeRoot). pull/push round-trip the file, run executes its recipes, compare A/Bs the traffic they produce, and check gates CI on the whole rule suite.

Command	What it does
`glassray-coach pull [--from local\|cloud] [--out glassray.yaml]`	Round-trip `glassray.yaml`. Also `pull --as-fixtures [--flow <id>] [--limit <n>] [--dir glassray/fixtures]` and `pull --traces <flow> [-n <count>] [--inputs-dir glassray/inputs]` to freeze corpora / inputs.
`glassray-coach push [--file glassray.yaml] [--dry-run] [--prune] [--target local]`	Reconcile the file into the store - a terraform-style plan/apply (`--dry-run` plans, `--prune` removes what the file dropped).
`glassray-coach run <flow> --label <name> [--file glassray.yaml]`	Execute the flow’s run recipe from `glassray.yaml`; traces land tagged with that run label (it becomes the trace `environment`).
`glassray-coach compare [<flow>] <baseline> <candidate> [--flow <id>] [--sample <n>]`	A/B two corpora over the rule suite. Corpus tokens: a bare token = a run label; prefixed `label:<x>`, `agent:<name>`, `flow:<id>`, `fixtures:<dir>`.
`glassray-coach check [--fixtures] [--dir glassray/fixtures] [--sample <n>]`	The CI gate: runs every rule and exits non-zero if any pass-rate is below its threshold.
`glassray-coach link <project> [--endpoint <url>] [--token <t>]` · `link --show`	Record a cloud project ref so local work can be pushed up.

LLM provider

Discovery, evals, flows, background classification, and replay need a model. Coach chooses one via GLASSRAY_LLM_PROVIDER:

Provider	Needs	Notes
`claude-subscription`	a local `~/.claude` (Claude Code)	Default when `~/.claude` exists. Zero-config, no API key.
`anthropic`	`ANTHROPIC_API_KEY`	A metered API key.
`openai`	`OPENAI_API_KEY`	A metered API key.
`mock`	nothing	Default with no `~/.claude`. Deterministic and offline - the airgap / CI path.

# Real analysis with an API key
GLASSRAY_LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-... npx @glassray/coach start

Every analysis call is metered against GLASSRAY_LLM_BUDGET_USD (default $50; 0 = unlimited). The free mock / claude-subscription paths accrue $0 and are never blocked.

You don’t have to set env vars - the dashboard’s Settings page lets you pick the provider, the heavy/light model ids, and the budget from dropdowns. Those choices persist to disk (settings.json, chmod 0600) and override the environment. API keys stay in the environment, never in Settings.

Environment variables

Every setting has a working default - a fresh run needs none of these.

Variable	Default	What it does
`GLASSRAY_HOME`	`~/.glassray`	Data directory (embedded database + local key).
`GLASSRAY_PORT` (or `PORT`)	`5899`	Port Coach binds on `127.0.0.1`.
`GLASSRAY_LLM_PROVIDER`	`claude-subscription` if `~/.claude` exists, else `mock`	Analysis backend (see above).
`GLASSRAY_HEAVY_MODEL_ID`	`claude-opus-4-8` (`gpt-4o` on `openai`)	Heavy-tier model id - applies to every provider.
`GLASSRAY_LIGHT_MODEL_ID`	`claude-sonnet-4-6` (`gpt-4o-mini` on `openai`)	Light-tier model id - applies to every provider.
`GLASSRAY_LLM_BUDGET_USD`	`50`	Metered spend cap; `0` = unlimited.
`GLASSRAY_RUN_TIMEOUT_MS`	`600000`	Backstop timeout for a background run so a stalled model call can’t wedge the queue; `0` disables.
`GLASSRAY_CLASSIFY_DEBOUNCE_MS`	`5000`	Quiet period after the last ingest before the background classify sweep runs.
`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`	-	Required by the matching metered provider.
`GLASSRAY_NO_UPDATE_CHECK`	-	Disable the npm update check entirely (also honors `NO_UPDATE_NOTIFIER` and `CI`).

Human-facing commands (the landing screen, start, status, init) print a one-line notice when a newer version is on npm - refreshed in the background at most once a day, with glassray-coach doctor doing the one live check. The check is a single HTTPS request to registry.npmjs.org containing only the package name, and it never runs from the server or the data commands - the egress guarantees for your trace data are unchanged.

Drive the whole loop from your coding agent

Coach ships its agent integration as a skill in the open Agent Skills format - one SKILL.md that works in Claude Code, OpenAI Codex, VS Code, and GitHub Copilot.

Install the skill

Pick whichever route fits how you manage skills - all three install the same file:

glassray-coach init
npx skills
Manual

The zero-thought route, bundled with Coach. From the repo your agent lives in:

glassray-coach init          # → ./.agents/skills/glassray/ + ./.claude/skills/glassray/

Installs to both standard locations - .agents/skills/ (the open standard: Codex, VS Code, Copilot) and .claude/skills/ (Claude Code) - idempotently; --force overwrites a locally edited copy.

Prefer a skills manager? The community skills CLI installs straight from the Coach repo into 70+ agents (Claude Code, Cursor, Codex, Windsurf, Cline, …):

npx skills add glassray/glassray-coach            # pick agents interactively
npx skills add glassray/glassray-coach -g         # user-wide instead of per-repo
npx skills add glassray/glassray-coach -a cursor  # target one agent

It discovers the skill from the repo’s skills/ directory and manages updates with npx skills update glassray.

It’s one file - copy it wherever your agent looks for skills:

mkdir -p .agents/skills/glassray
curl -o .agents/skills/glassray/SKILL.md \
  https://raw.githubusercontent.com/glassray/glassray-coach/main/skills/glassray/SKILL.md

Claude Code reads .claude/skills/, Codex reads .agents/skills/, VS Code + Copilot read both (and .github/skills/).

What the skill does

The skill teaches the coding agent the full workflow over the CLI, server-first - flows and rules are created in the server (what the dashboard shows), and glassray.yaml is the committed snapshot: inventory the durable state first (flows list / evals list - flows persist across sessions, so nothing gets re-created), delegate flow discovery to Coach’s own code explorer (flows discover --code-root reads your source and writes flows + code-anchored rules straight into the server), review and tighten what it found, wire tracing and verify one trace end-to-end, snapshot with pull, and self-correct vague flow definitions with flows audit. It finishes with a coverage report - behaviours found vs instrumented vs skipped. Because every command emits stable JSON, what Claude sets up in one terminal session is exactly what the next session finds.

The easiest entry needs no typing at all: on an empty store, glassray-coach start and the dashboard’s empty state hand you a copy-paste onboarding prompt that drives this whole setup. And once flows and evals exist the loop stays closed on its own: Coach classifies new traffic in the background and auto-reruns each flow-bound eval once enough new member traces land (autorun is on by default; tune or disable it per rule) - apply a glassray-coach fix, send fresh traffic, and the reruns happen without you. glassray-coach evals run <id> forces one immediately.

Data & privacy

Everything lives under ~/.glassray (an embedded PGlite database + a local API key, chmod 0600). Coach binds 127.0.0.1 only and enforces a loopback guard on every route - nothing is uploaded, and there’s no account. To start fresh, glassray-coach reset --yes.

Get started

Glassray CLI

Coach (local)

Concepts

Trace sources

Glassray SDK

Integrations

Explore

CLI & coding agents

Install & upgrade

Server commands

Data commands

Loop verbs (harness & CI)

LLM provider

Environment variables

Drive the whole loop from your coding agent

Install the skill

What the skill does

Data & privacy

​Install & upgrade

​Server commands

​Data commands

​Loop verbs (harness & CI)

​LLM provider

​Environment variables

​Drive the whole loop from your coding agent

​Install the skill

​What the skill does

​Data & privacy

Install & upgrade

Server commands

Data commands

Loop verbs (harness & CI)

LLM provider

Environment variables

Drive the whole loop from your coding agent

Install the skill

What the skill does

Data & privacy