> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xynthis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Watchers

> Declarative pollers that watch a folder or a command's output and feed changes into the brain.

A watcher makes Xynthis proactive about something you care about: a folder of documents, the output of `git status`, a Kubernetes namespace. The brain polls the source on an interval you set; when something changes, the change flows into memory as a perception, and the agent sees it on its next turn.

Watchers live in the brain, persisted to `watchers.json` in its data directory, so they survive daemon restarts.

## Creating a watcher

The simplest way is to ask in chat ("watch my \~/Notes folder and tell me when new markdown files appear") and the agent creates one with its `watcher_create` tool. You can also call the tool directly:

```bash theme={null}
xynthis tool watcher_create --args '{
  "name": "notes-inbox",
  "provider_kind": "files_changed",
  "provider_config": { "root": "/Users/you/Notes", "patterns": [".md"] },
  "interval_secs": 60,
  "action_prompt": "summarize the new file and store the summary"
}'
```

The response includes the watcher id (`w_...`), which you need for deletion.

Two provider kinds exist:

**`files_changed`** watches a directory tree for new or modified files. `root` is the absolute path; `patterns` is an optional list of substring filters on the path (an empty list matches every file).

**`command_output`** runs a command at each interval and fires when its stdout changes:

```bash theme={null}
xynthis tool watcher_create --args '{
  "name": "repo-drift",
  "provider_kind": "command_output",
  "provider_config": { "command": "git", "args": ["status", "--short"], "cwd": "/Users/you/project" },
  "interval_secs": 120
}'
```

The command is exec'd directly, not through a shell, so there are no pipes, globs, or `$VAR` interpolation; arguments go in the `args` array. `cwd` is optional; a relative path resolves against your home directory. The brain does not sandbox the command, so stick to read-only commands like `git status`, `kubectl get pods`, or `pgrep`.

The minimum interval is 15 seconds. The first poll establishes a baseline silently; subsequent polls fire only on change. A failing poll (bad path, command error) is logged and does not retry until the next interval, so a broken watcher cannot hot-loop.

## What happens when a watcher fires

Each detected change becomes a `watcher_event` perception (`[watcher:notes-inbox] <what changed>`) that goes through the same ingest path as everything else: working memory, the Binary Memory Core, and the knowledge graph. The next agent turn sees it in context.

The optional `action_prompt` is appended to every event, so the agent knows what you want done when it encounters one ("summarize the new file and store the summary").

**Unaddressed events get a follow-up.** The brain's proactive engine checks every 5 minutes for watcher events that have been sitting in working memory between 15 minutes and 24 hours without anything newer referencing them. Each such event gets one `proactive_followup` perception that surfaces it loudly on the next turn: Xynthis nudges once rather than nagging.

## Listing and deleting

```bash theme={null}
xynthis tool watcher_list --args '{}'
```

```
- w_19a1b3f2 notes-inbox provider=files_changed interval=60s enabled=true last_run=1783041600 last_event=never
```

```bash theme={null}
xynthis tool watcher_delete --args '{"id": "w_19a1b3f2"}'
```

Deleting a watcher stops the polling and removes it from `watchers.json`. Perceptions it already produced stay in memory.

<Note>
  Folders you index with `xynthis corpus add` get their own change-watching automatically; that is a separate, event-driven mechanism for keeping the corpus index fresh, not a watcher. Use watchers when you want the *agent* told about changes; see [Codebase memory](/guides/codebase-memory) for corpus watching.
</Note>