---
description: >-
  How a .watcher-ignore file keeps one directory's coding-agent sessions off your Watcher deployment, and what it leaves unchanged.
---

> Part of the Watcher docs. Index of all pages, with summaries: https://watcher-docs.apolloresearch.ai/llms.txt
> Before upgrading Watcher, read the release pages and full changelogs for every version crossed: https://watcher-docs.apolloresearch.ai/releases/index.md
> Found an issue with this page? Report it: https://github.com/ApolloResearch/watcher-bin/issues/new?title=Docs%20feedback%3A%20Excluding%20a%20directory%20with%20.watcher-ignore&body=Page%3A%20Excluding%20a%20directory%20with%20.watcher-ignore%0AURL%3A%20https%3A%2F%2Fwatcher-docs.apolloresearch.ai%2Fclient%2Fwatcher-ignore%2F%0A%0A

# Excluding a directory with .watcher-ignore

A `.watcher-ignore` file marks a directory whose coding-agent sessions the
[Watcher client](index.md) does not upload. Sessions covered by it are never
ingested, so they do not appear in the [Analyzer](../concepts/analyzer.md) and
are never sent to an LLM [grader](../concepts/graders.md). They still run under
the client's hooks, and the deterministic parts of
[blocking review](../concepts/blocking-and-trailing-review.md) 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](../concepts/organization-settings.md#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 to show in the client's
local UI, shortened if it is long, and 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.

## 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-count 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.

## Seeing that a session is excluded

The session is listed in the client's local UI marked `Not ingested`, with the
reason and the path of the file that excluded it. In Claude Code the statusline
carries a `Session excluded from Watcher` badge while the working directory is
excluded. Codex has no statusline, so there is no in-terminal indication there.

## 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](../concepts/blocking-and-trailing-review.md#enforcement-modes).