Watcher: Technical Details for Teams

Apollo Research · July 2026

What Watcher does

Watcher integrates with coding agents to apply AI-based risk scoring to every action, and only interrupts when it matters.

• Engineers keep using coding agents without changing their workflow.
• Watcher Live runs locally, monitoring agent activity in real time and blocking risky actions before they execute.
• Broader security issues and trends are surfaced asynchronously. Watcher Analyzer gives security and engineering leads a view of these across the organization.
• Security teams define organization-wide guardrails. Use our research-backed monitors, and add your own to match specific threat models.

Watcher Live

Watcher runs alongside the agent CLI (i.e. Claude Code or Codex). When a tool call is flagged, Watcher can auto-approve, auto-deny, or escalate to the developer with the risk score and an explanation. Engineers only review actions that genuinely require human judgment.

Watcher Live also provides a local UI to manage sessions and approvals in one place. It shows active coding agent sessions, the approval decisions Watcher is making, and any actions that need human attention.

Watcher Live runs two types of monitors:

• Blocking monitors intercept individual tool calls in real time and decide whether to allow, deny, or escalate to a human. These catch actions that could cause irreversible harm. E.g., tearing down infra, leaking secrets, pushing code without approval.
• Trailing monitors evaluate the full session trajectory periodically in the background. They catch patterns that no single action would reveal: the agent drifting off task, confidently implementing the wrong fix, or claiming it's done without actually verifying.

If a single action could cause harm, it gets blocked before execution. If the risk is a pattern across multiple actions, trailing monitors pick it up in the background.

How blocking works

When a coding agent tries to use a tool (run a command, edit a file, push code), Watcher intercepts the request and runs it through a multi-stage evaluation pipeline. Each stage is more thorough but slower than the last, so most requests resolve early in the pipeline. You can set the score thresholds to match your security policies.

Most safe actions (reading files, running tests, standard edits) are resolved at the rules or triage stage in under 2 seconds. Only genuinely ambiguous or risky actions reach the full evaluator, and only a small fraction of those require human input. The total overhead created by Watcher is typically 1–5%, though users likely save time overall by preventing bad actions before they happen.

The multi-stage design is a latency/accuracy tradeoff. A single large model evaluating every action would be too slow: coding agents make hundreds of tool calls per session, and each blocked call is a second the developer waits. Rules handle the easy cases instantly. Triage handles the next tier with a small, fast model. The full evaluator only runs on the fraction of requests that triage couldn't confidently approve, and it gets richer context: more of the transcript, the triage model's assessment, and a history of recent human decisions on the same session.

Actions that go through the grading pipeline can be auto-denied if the score crosses the deny threshold; Watcher feeds the reasoning back to the coding agent, which can adjust and continue without human intervention. If the score falls in the escalation range, Watcher asks the engineer to approve, deny, or revise. For specific tools or commands, Watcher can be set to always escalate for human approval.

Each stage of the pipeline is configurable:

Rules

Command rules provide zero-latency pattern matching, the first line of defense. Each rule is a regex pattern on the tool name and command/file path, with one of four actions:

Watcher comes with ~60 built-in rules covering common safe and dangerous patterns. You can add custom rules via the Rules panel.

Thresholds

Each tool type has a configurable escalation mode:

By default, read-only tools like Read, Grep, and WebSearch are set to auto-approve. Tools that modify state like Bash, Edit, and Write default to "Escalate >= 6". Plan-related tools like ExitPlanMode default to always escalate.

These defaults ship with Watcher and can be overridden by admins through the YAML configuration described below.

Policy

The Policy panel lets you view and edit the prompts that drive the triage and gateway models. Each model has a system prompt that defines what it should look for, how it should score requests, and what context to consider. You can also choose which model each grader uses (e.g., Gemini Flash for fast triage, Claude Sonnet for the gateway).

This is where you customize what Watcher considers dangerous, beyond just the rules and thresholds. If your team has specific security concerns (e.g., you work with medical data and need strict PII detection), you can adjust the grader prompts to reflect that.

How trailing monitors work

Not all failure modes need to be caught before an action happens. Some are easily reversible, and some patterns only emerge over multiple turns. Trailing monitors periodically evaluate a window of the session transcript and score it across configurable dimensions, chosen based on the most common failure modes we observed in real coding agent sessions.

Each dimension gets a 1–10 score (higher is worse). The monitor evaluates the full arc of the conversation: what did the user ask for, what is the agent actually doing, and where are the gaps?

The current default security monitor scores nine harm-graded dimensions:

The grading is harm-based: it focuses on organizational consequence and blast radius, not just whether the agent's behavior looked odd. The same action may score lower in an ephemeral sandbox with fake data and higher in production with real credentials, public exposure, or cross-team impact.

Trailing monitors can use more capable models because latency is less important.

Suggestion injection. When trailing monitor scores exceed a configurable threshold, Watcher can automatically inject a suggestion into the agent's context. This is a gentle course correction that appears as a system reminder. In practice, agents generally follow these suggestions, though the effectiveness depends on the model and how far the agent has already committed to the wrong path.

Claude auto-mode, Codex auto-review mode

Products like Claude Code's auto-mode and Codex's auto-review mode address the same core problem: reducing permission fatigue while maintaining safety. We think these are good products and are glad the labs are investing in safety by default.

Watcher comes at the problem from a different angle:

• Consistent rules across all coding agents. Watcher integrates across Claude Code and Codex. Your security policies are defined once and applied everywhere, rather than configured separately in each tool.
• Organization-wide visibility. Auto-mode and auto-review are designed for a single developer using a single agent. Watcher gives teams centralized policy management, multi-session supervision, and Analyzer for reviewing failure patterns across all developers and sessions.
• Cross-model monitoring. Built-in safety features use models from the same company as monitors. In practice, we've found that different models have different blind spots and biases. GPT models tend to be overly suspicious, Claude models can be too trusting of their own reasoning. Watcher lets you mix models across the pipeline (e.g., Gemini Flash for fast triage, Claude Sonnet for gateway) to get monitoring that doesn't share the agent's biases.
• Admin-managed policy. Built-in modes are developer-controlled. Watcher supports locked settings, admin-distributed rules, and MDM deployment so that security teams can enforce policy, not just suggest it.

Apollo is working directly with the auto-mode and auto-review teams at Anthropic and OpenAI to ensure Watcher integrates well with these features as they evolve. The goal is not to replace built-in controls, but to provide the organizational layer on top of them that security teams need.

Watcher Analyzer

Analyzer is the web-based review surface for security teams. It is available in Apollo's cloud-hosted setup or as part of a self-hosted deployment.

Analyzer provides organization-level visibility. You can see summary stats (total sessions, blocked actions, flagged sessions, failure rate), a breakdown of failures by category, and trends over time. A filterable session list lets you sort by severity, status, or date, filter by failure category, and search by session ID or repo. Clicking into a session opens the full transcript with grades and explanations alongside each message.

Slack alerts

When Analyzer flags a session, Watcher can push an alert to a configured Slack channel. Teams can set the severity threshold for alerts depending on their preferences. Alerts include the finding category, the user, the coding agent, and a direct link to investigate the session in Analyzer.

Security teams don't need to be watching Analyzer constantly. Flagged sessions go straight to Slack.

Supported coding agents

Watcher currently supports Claude Code and Codex. Copilot and Cursor are next on the roadmap.

The integration layer is hook-based and designed to support additional coding agents. Different agents expose different lifecycle and permission events, so adding support generally means adding an agent-specific hook package and installer while reusing the shared Watcher policy and grading pipeline.

If a team is using another coding agent, they should talk to Apollo. We can prioritize support where there is customer demand.

Deployment options

Watcher can be deployed in two ways, and both can be tailored to fit your infrastructure and compliance needs. We're open to different deployment configurations.

Apollo-hosted

Developer machines run the Watcher client and hooks locally, while session storage, grading, and Analyzer run on Apollo's cloud infrastructure. This is the fastest path to a pilot. Apollo manages the backend, grading infrastructure, and operational maintenance.

Apollo can sign NDAs, DPAs, and share standard agreements to address data protection and procurement concerns.

Self-hosted

The customer runs the Watcher backend and Analyzer in their own environment. Developer machines still run the Watcher client and hooks, but send trajectories to the customer's Watcher deployment instead of Apollo's hosted backend.

The self-hosted distribution includes:

• Watcher API backend.
• Analyzer single-page web app.
• Postgres, either bundled in Docker or provided as a managed database.
• Docker Compose deployment.
• Support for the customer's TLS-terminating reverse proxy or load balancer.
• Support for customer-managed authentication via a reverse proxy that injects identity and role headers.
• Alternatively, Apollo can manage authentication for you, using WorkOS by default (SSO, SAML, and directory sync).

Typical self-hosting requirements:

• Linux Docker host with Docker Engine and Compose.
• Reverse proxy or load balancer for TLS.
• Authentication layer, if you manage auth yourself (oauth2-proxy, Pomerium, Authelia, AWS ALB with OIDC, Cloudflare Access, or an existing SSO appliance). Otherwise Apollo can manage it for you via WorkOS.
• LLM API keys for grading. Anthropic and Google are required for the default graders; OpenAI is also supported.
• Optional managed Postgres for production-style deployments.

Organization rollout

Watcher is designed to be rolled out by administrators rather than installed manually by every engineer.

1. Security or platform engineering chooses a deployment: Apollo-hosted or self-hosted.
2. Apollo provides an installation command and organization configuration.
3. Admins distribute that command through their device management system.
4. The installer configures Watcher locally and installs hooks into supported coding agents.
5. Developer sessions begin appearing in Analyzer for authorized reviewers.

Hooks fire on session lifecycle events, user prompts, tool usage, permission requests, and session end. After installation, developers continue with their usual workflow. Watcher also runs as a local real-time UI.

Organization-wide settings and YAML configuration

Security teams can define organization-wide Watcher settings in YAML and distribute them to developer machines through MDM.

Watcher uses a layered settings model:

• Apollo ships built-in defaults with Watcher.
• Admin-managed settings are distributed through an organization-level settings.yaml file.
• User-specific overrides are stored separately.

Apollo can update bundled defaults, admins can override or lock specific settings, and users can keep local preferences where the admin policy allows it.

The YAML settings model covers command rules, tool thresholds, monitor selections, blocking policy settings, turn review, suggestion settings, and UI preferences.

Settings support permissions at the field and section level:

The Watcher UI receives lock metadata from the API, so locked controls are visibly disabled instead of appearing editable and then failing on save.

Illustrative admin settings file:

version: 1
permission: modifiable

ui:
  permission: modifiable
  persist_shell_terminals: true
  window_management:
    value: claude-in-watcher
    permission: locked

policy_monitors:
  permission: locked
  policy_gateway_grader_id: c0000001-0000-0000-0000-000000000001
  policy_triage_grader_id: c0000001-0000-0000-0000-000000000002
  pretool_guard_grader_id: c0000001-0000-0000-0000-000000000003
  triage_max_allow_score: 2
  context_user_messages: 4
  pending_orphan_timeout_seconds: 30

turn_review:
  permission: modifiable
  enabled: false
  trailing_grader_id:
    value: 00000000-0000-0000-0000-000000000001
    permission: locked

suggestions:
  permission: locked
  score_threshold: 6
  previous_score_threshold: 8
  prompt_template: |
    {findings_text}

tool_thresholds:
  permission: locked
  Bash:
    flag_threshold: 4
    deny_threshold: 8
    common: true

command_rules:
  permission: additions_allowed
  rules:
    - id: admin-git-force-push
      tool_name: Bash
      name: Escalate force push
      category: git
      regex: '^git\s+push\b.*\s--force\b'
      decision: human
      priority: 35

The YAML is designed to be self-documenting. The settings loader validates on startup and surfaces errors to the UI rather than silently overwriting bad files.

curl -fsSL https://github.com/ApolloResearch/watcher-bin/releases/latest/download/install.sh | bash -s -- --cloud
# Restart or open a new terminal
watcher