Background watcher

The watcher is a local background process that imports new history from the configured sources. It also refreshes indexes and runs enabled scheduled tasks such as memory backup, provider CLI usage sampling, and remote sync.

Manage the watcher in the app

Open Settings → Indexing & Imports to review the live configuration. Choose Automatic to follow every locally detected harness or Custom to edit Sources scanned. Set Watcher rolling window (days) for routine passes, and check the Watcher status pill after saving. Pause search indexing stops derived search refreshes but does not stop conversation imports.

Use Conversations to verify the result: open Filter & sort, choose the expected Source, and set Time to the recent window. The app manages source selection and indexing preferences, but starting, stopping, restarting, or tailing the background process remains a terminal operation. A full-history backfill also remains explicit through hansard import --since all.

Configure and start it

Choose the sources to monitor.
Terminal window
```
hansard config sources edit
```
For unattended setup, pass an explicit list:
Terminal window
```
hansard config setup --watch-sources codex-cli,claude,cursor
```
Set the rolling import window if the default is not appropriate.
Terminal window
```
hansard config set imports.defaultSinceDays 90
```
Start the watcher and verify its state.
Terminal window
```
hansard watcher start
hansard watcher status
```

The rolling window bounds routine scans; it does not delete older archived sessions. Use an explicit --since all manual import for a complete backfill.

Lifecycle commands

Command	Purpose
`hansard watcher status`	Report whether the watcher is running and show its process ID.
`hansard watcher start`	Start the watcher as a detached local process.
`hansard watcher start --foreground`	Run it in the current terminal for direct diagnostics.
`hansard watcher stop`	Stop the running watcher.
`hansard watcher restart`	Stop it if necessary, then start a new process.
`hansard watcher logs`	Print watcher logs.
`hansard watcher logs --follow`	Continue streaming new log entries.

Enable a user-level login item when the watcher should start after sign-in:

hansard watcher login enable
hansard watcher login status

Remove it without changing the archive or watcher configuration:

hansard watcher login disable

Reload after a package upgrade

Install a normal package upgrade without rebuilding the archive:

npm install -g hansard@latest

Restart the watcher only when it was already running:

hansard watcher restart

Reopen an active Hansard app or browser viewer so its server also loads the new package version.

How freshness works

The watcher combines filesystem events with periodic checks:

Watched source roots trigger targeted imports after nearby writes settle.
A 30-second watcher pass schedules work, handles sources without usable filesystem events, and retries interrupted tasks.
Fresh filesystem-backed transcript writes preempt remaining scheduled heartbeat scans. Optional Codex subagent-message recovery runs at most once after pending transcript imports are clear.
Watched sources receive a periodic safety check even when no event arrives.
Repeated empty polling for a source slows down to avoid unnecessary work.
Failed source imports use increasing retry delays instead of looping rapidly.

Imports share one serialized lane so two provider scans cannot write overlapping archive state concurrently. If activity arrives while an import is running, it remains pending and is promoted ahead of unrelated heartbeat work in the next pass.

Scheduled work

When configured, the same process also:

refreshes the search and session-list indexes after imports;
backs up reachable provider memories every 15 minutes;
samples quota and activity data from supported signed-in provider CLIs every 15 minutes when usage tracking is enabled and the Mac is awake;
runs remote sync at the configured interval; and
processes enabled notification work.

On a fresh init, CLI usage tracking follows the login-watcher default; unattended --autostart also selects tracking unless --no-track-usage is passed. After setup, these jobs remain independent preferences. Starting the watcher does not enable remote sync, CLI usage tracking, or notifications by itself.

The Usage page distinguishes provider quota windows from activity-only counters. Codex, Claude, Antigravity, Devin, and Grok Build expose supported quota surfaces. Antigravity’s documented /usage panel supplies its account and grouped weekly limits; devin auth status supplies Devin account and plan identity before its quota check. OpenCode contributes 30-day local session, message, and token counters. These probes do not send a model prompt.

Sleep pauses scheduled sampling. A later capture resumes the series, but missed 15-minute samples cannot be reconstructed or backfilled.

Diagnose delayed imports

Start with runtime state and the live log:

hansard status
hansard watcher status
hansard watcher logs --follow

Then compare automatic behavior with a direct source import:

hansard import --source cursor --since 30d --dry-run --explain-skips
hansard import --source cursor --since 30d

If the direct import works, restart the watcher to recreate its process and filesystem watches:

hansard watcher restart

A log entry saying tick skipped: previous tick still running means the prior watcher pass has not finished. It usually indicates an import backlog or a slow provider scan rather than a stopped process. Fresh source events remain queued and preempt the remaining heartbeat scans after the active worker exits. Follow the log to the source that is still running, then use hansard doctor to check dependencies and source availability.