Skip to main content
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: 
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: 
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

xynthis tool watcher_list --args '{}'

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

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.
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 for corpus watching.