Excluding a directory with .watcher-ignore

A .watcher-ignore file marks a directory whose coding-agent sessions the Watcher client does not upload. Sessions covered by it are never ingested, so they do not appear in the Analyzer and are never sent to an LLM grader. They still run under the client's hooks, and the deterministic parts of blocking review still apply.

The mechanism is off unless an administrator has enabled it for the machine, in the admin settings baseline or through managed client settings. While it is off, a .watcher-ignore file changes nothing.

Where the file goes

The file must be named exactly .watcher-ignore, and it must be a file rather than a directory. Where you put it decides which sessions it covers:

• Inside a git repository. The client looks for the file in the session's working directory and in each directory above it, up to and including the repository root, and never above that root. A .watcher-ignore at the repository root therefore covers the whole repository.
• Outside a git repository. Only the session's own working directory is checked, with no walk upwards. A file in a parent directory covers sessions started in that exact directory and nothing beneath it.

There is no home-directory or machine-wide location for the file.

Existence is the whole rule

There is no pattern syntax. The contents are never matched against paths: a .watcher-ignore that exists excludes, and an empty one excludes just as well.

The first non-empty line is read as a short reason, shortened if it is long, which watcher doctor settings shows. The rest of the file is ignored. A file the client cannot read still excludes.

What a marker covers

Exclusion is resolved per session from the session's working directory, not per file the agent touches. A session picks up the exclusion of the directory it starts in and stays excluded while the marker is in place, including work it does elsewhere, so start the agent in the directory you want excluded.

Exclusion is evaluated at each hook event, not fixed when the session starts, so adding or removing the file takes effect within seconds, with no restart of the client or the agent. A session that is already running stops uploading at its next hook event after the file appears.

Removing the file resumes uploading at the next hook event, and for a session that was never ingested that upload carries its whole transcript so far, including the work done while the marker was in place. End a session before removing the marker if the work it has already done must stay private. Anything already uploaded stays uploaded: the file prevents uploads, it does not withdraw them.

Background recovery remembers exclusions it observes and keeps those sessions local even after the marker is removed or the client restarts. A new hook event uses the current policy. Subagents inherit exclusions from their ancestors; excluding a child alone does not exclude its parent or siblings.

What still applies

Excluding a directory is not a way to turn Watcher off:

• The client's hooks still run in the agent.
• Deterministic blocking review still intervenes. A tool threshold set to always deny, and a command rule, still deny a call or, while the machine is enforcing, escalate it for a human to approve.
• Only the LLM grading is skipped, so a call that would have needed grading falls through to the coding agent's own permission flow. A session that started elsewhere, worked in an excluded directory and then left it is different: Watcher refuses to grade its calls and applies the configured failure decision instead.

Seeing that a session is excluded

In Claude Code and GitHub Copilot CLI the status line carries a Session excluded from Watcher badge while the working directory is excluded. Codex has no status line, so there is no in-terminal indication there.

To check a directory, run watcher doctor settings from it. The report says whether a .watcher-ignore file excludes that directory, with the reason and the file's path, or that this machine does not honor these files.

Creating the file

Create the file yourself rather than asking a coding agent to do it. Watcher's built-in command rules put a direct agent attempt at the file to a human to approve: editing or writing that path, applying a patch to it, or a common shell command that creates it. The rules are pattern matches on the call, so they guard against direct attempts rather than covering every indirect way a shell command could write the file, and whether the call reaches a human also depends on the machine's enforcement mode.