Concepts

This page is the glossary for the Watcher vocabulary used across these docs, linking to the full concept page where one exists.

Term	Definition
Session	One recorded interaction with a coding agent, such as a single Claude Code or Codex conversation on a developer's machine. A session contains one or more trajectories. See Sessions and trajectories.
Trajectory	One linear path through a session's conversation: an unbroken chain of messages ending at one of the session's latest messages. Graders review trajectories. See Sessions and trajectories.
Grader	A versioned grading rubric: a prompt plus score dimensions that an LLM applies to a trajectory, producing a grade: one value per dimension, plus optional explanation and summary text. Watcher ships built-in graders, and you can create your own. See Graders.
Managed monitor	A grader Watcher manages end to end, prompt and model included, addressed by role rather than by ID and updated with Watcher releases. An organization shapes managed monitors with custom instructions instead of editing them; the Analyzer calls an organization's own graders custom monitors to distinguish them. See Graders.
Severity	A score band: low (1-3), medium (4-6), high (7-8), or critical (9-10). Sessions use the latest deep-review verdict; tool calls use the gateway score, or triage when applicable; missing scores are not a low-severity verdict (see Analyzer severity).
Blocking review	Review of a tool call before it runs. The outcome allows the call, denies it, or escalates it to a human for approval. See Blocking and trailing review.
Tool threshold	A per-tool pair of scores, flag and deny, that blocking review compares a grader's score against. A pair set to a terminal value decides the call without grading; a tool with no entry of its own uses the unknown fallback pair. See Blocking and trailing review.
Command rule	A regular expression, scoped to one tool name or a glob, matched against a tool call's command text, file path or other arguments before any grader runs. A match allows the call, denies it, escalates it to a human, or sends it to grading. See Blocking and trailing review.
Triage	Blocking review's fast, cheap grading stage. It can only auto-approve a low-scoring call; anything else goes on to gateway review. Its managed monitor role is triage. See Blocking review.
Gateway review	Blocking review's deciding grading stage. The gateway grader scores the call from 1 to 10 and the tool's thresholds turn that score into allow, deny, or escalate. Its managed monitor role is gateway. See Blocking review.
Trailing review	Server-side grading that follows ingested sessions: summaries while a session runs and after it settles, plus a deeper security review of highly scored sessions. See Blocking and trailing review.
Deep Review	Trailing review's second, more thorough security grade of a session. It runs on the server after a session the blocking pipeline scored highly settles, or when a user requests one for any session, and drives session severity. Its monitor role is deep_review. See Trailing review.
Subagent coverage	Review of subagent tool calls through the coding agent's hooks. Coverage depends on which calls the agent sends for review and does not imply a complete record of the subagent's conversation. See Subagent coverage.
Org viewer	The org-viewer role grants organization metrics and all session findings, but only the user’s own session content. It does not grant organization-settings access. See Roles.
Organization settings	Org-wide configuration managed by admins in the Analyzer, such as Slack notifications for flagged sessions. See Organization settings.
Admin audit log	An append-only file on a self-hosted deployment recording admin access to other users' session data, organization-level writes, and system-attributed retention scrubs, one JSON line per event. See Operations.
Analyzer	Watcher's web dashboard: where your team reviews sessions and tool calls with their grades, works on graders, and where admins manage organization settings. See Analyzer.
Login agent	The per-user background service that starts the Watcher client on login and keeps it running: a LaunchAgent on macOS, a systemd user unit on Linux. Installed by the first plain watcher run, or by watcher autostart install. See Client.
Gateway hook	An API integration that sends a conversation and tool call to Watcher for evaluation and recording without a client on the developer's machine. Enforcement-capable callers apply returned decisions according to the configured enforcement mode; Aperture only observes. See Gateway hooks.
Session source	How a session's messages reached Watcher, shown as badges and as the Source filter in the Analyzer: Watcher Live for the Watcher client, Aperture for Tailscale Aperture, or one of three labels for other gateway hooks. Gateway marks a session whose conversation ID starts with a gateway example's prefix, such as litellm:. Watcher SDK marks a registered SDK coding agent's prefix, such as github-copilot-cli:. Hooks API covers any other ID or none, including your own agent sending gateway hooks through the Watcher SDK with its own conversation ID. The labels affect display and filtering only. See ingestion sources.
Watcher API	The HTTP interface your deployment serves for programmatic access to sessions, trajectories, grades, and graders. See API.
Watcher SDK	The typed Python client for the Watcher API (package watcher-sdk), with an optional watcher-sdk command line and integration examples built on it, such as the Copilot integration. Not to be confused with the Watcher SDK session source, which marks only registered SDK coding agents. See Python SDK and Integrations.
Watcher client	The program installed on each developer machine. It hooks into coding agents (Claude Code, Codex) to record sessions, upload them to your Watcher deployment, and enforce blocking review. See Client for installing and using it.
Supported agents	The coding-agent environments Watcher integrates with. Supported agents lists local integrations and the Aperture agent/provider support table.
Enforcement mode	The administrator's setting that selects enforce, observe, or paused behavior for the Watcher client and gateway hooks. Paused clients and gateway hooks evaluate nothing, not even rules or thresholds. See Blocking and trailing review and Gateway hooks.
Snooze	Temporarily skips LLM grading without changing the enforcement mode. Command rules still run. See Snoozing.
Managed client settings	An admin-authored overlay of Watcher client settings, edited in the Analyzer and delivered to developer machines by client pull (when distribution via Watcher is on) or by your MDM, with per-value locking. See Organization settings.
Settings profile	A named bundle of the Watcher client's review settings that is switched as a unit, such as the built-in Default and Human in the Loop profiles. See Client.
.watcher-ignore	A file a developer puts in a directory to keep the coding-agent sessions started there from being uploaded to the deployment or LLM-graded. Honored only where an administrator has enabled it, and it does not stop deterministic blocking review. See Excluding a directory with .watcher-ignore.
Red-team drill	A prompt an admin downloads from the Analyzer and sends to a developer, whose AI assistant uses it to turn enforcement on for that one machine, probe an agreed threat model, and restore the machine. See Organization settings.