Background archiving

The watcher is a background process on your machine. It imports new sessions from your local harnesses as you work, keeps the search index current, and runs the scheduled tasks you turn on, such as memory backup, usage sampling, and sync.

Manage the watcher in the app

1. Open Settings → Imports.

2. Under Status, check that Background import reads Running. Hansard starts a watcher that stopped on its own, so it may read Starting for about a minute. To stop the watcher, select Stop. It finishes the current import first, and it stays stopped until you select Start, or until your next login while Start at login is on.

3. Turn Start at login on or off. Turning it off keeps a running watcher running.

4. Under Agents, set Selection to Automatic to follow every supported harness installed on this computer, or to Custom to turn individual harnesses on or off.

5. Under History, set Look-back window to how many days back each watcher pass looks.

Pause search updates stops search index updates but keeps importing sessions. Sessions imported while it is on stay out of search until you turn it back off.

To check the result, open Sessions, select Filter & sort, choose the harness under Source, and set Time to a recent range.

Startup at login is on by default. Hansard keeps the watcher, the account router, and remote access running unless you stopped them: when one stops on its own, after a crash, a restart that did not finish, or an update, the app, its menu bar item, remote access, and the next hansard command start it again within about two minutes, and the title band reads Starting the watcher… meanwhile. When startup at login was lost, for example after a restart, Hansard turns it back on. If it cannot, for example because Hansard is off in System Settings → General → Login Items, the title band says so. If you turned startup at login off yourself, in setup or with hansard watcher login disable, Hansard leaves it off. Set HANSARD_KEEP_SERVICES=0 to keep Hansard from starting them.

On macOS, the desktop app starts the watcher through its own login item, which System Settings → General → Login Items lists as Hansard. The watcher then reads Documents, Desktop, Downloads, cloud storage folders, other apps’ data, and external and network drives only where macOS allows the Hansard app, and skips the rest without asking. Settings → Imports → macOS access lists each of these permissions, and Ask macOS asks for the ones not answered yet. See macOS login items and folder access.

The watcher imports with the code of the copy of Hansard that started it. When the desktop app is installed or updated while the watcher runs an older release from a source checkout, an npm installation, or another copy of the app, Hansard stops that watcher and starts it from the app, with startup at login when that was on. A watcher that runs the same or a newer release, such as a source checkout ahead of the app, keeps running. The other way around works too: a watcher that runs from a source checkout or an npm installation moves itself to a newer build of Hansard installed on the same computer within about fifteen minutes, without the app opening, and the remote host does the same. A watcher that runs from the app moves only to a newer app, so it keeps the folder access macOS gave the app. hansard status names the copy the watcher runs, and Settings → Imports shows it as Watcher version.

The app controls source selection and indexing, and can start and stop the watcher. To restart the watcher, or to read its log, use the CLI. A full-history import also runs from the CLI with hansard import --since all.

Set up the watcher from the CLI

1. Choose the sources to watch.

   hansard config sources edit

   For a scripted setup, pass the list directly:

   hansard config setup --watch-sources codex-cli,claude,cursor

2. Change the rolling window if the default of 30 days does not suit you.

   hansard config set imports.defaultSinceDays 90

3. Start the watcher and check that it is running.

   hansard watcher start
   hansard watcher status

The rolling window limits how far back routine passes look. It never removes older sessions from the archive. For a complete backfill, run hansard import --since all.

Watcher commands

Command	What it does
hansard watcher status	Shows whether the watcher is running, its process ID, the copy and release it runs from, and a watcher move or archive refresh in progress.
hansard watcher start	Starts the watcher in the background.
hansard watcher start --foreground	Runs the watcher in the current terminal, for troubleshooting.
hansard watcher stop	Stops the watcher.
hansard watcher restart	Stops the watcher if it is running, then starts it again.
hansard watcher adopt	Moves the watcher, and startup at login when it is on, to the copy of Hansard that runs the command.
hansard watcher logs	Prints the watcher log.
hansard watcher logs --follow	Keeps printing new log entries as they arrive.

To start the watcher when you sign in to your computer:

hansard watcher login enable
hansard watcher login status

To stop starting it at sign-in, without changing the archive or the watcher’s settings:

hansard watcher login disable

Restart after an upgrade

Upgrading the CLI does not require rebuilding the archive:

npm install -g hansard@latest

A running watcher moves to the new version on its own, once nothing it started is still running. To move it right away, restart it:

hansard watcher restart

If the app or hansard web is open, close and reopen it so it also uses the new version.

After the upgrade, the watcher brings older archived conversations up to the new version’s files in background batches, and hansard status shows its progress as Archive refresh. See Refresh after updates.

How the watcher finds new sessions

0 min5 min10 min15 min

Sources that report file changesMost local harnesses

Session writtenImportedHeartbeat check

Sources checked by pollingStores without file events

Four empty checksEvery 5 minutes

Scheduled tasksMemory backup, classification, plan usage

Every 15 minutes

File writtenImportedCheck for new sessionsScheduled task

A source that finds new sessions goes back to the fast schedule. A failed import retries after 1 minute, then waits longer each time, up to 30 minutes.

The watcher combines file change events with regular checks:

• It watches each source’s folders and imports after 2 quiet seconds, with a 10-second maximum wait during continuous writes. SQLite sources use a wider 5-second quiet window and 30-second maximum.
• Codex also checks up to 256 recent or event-signaled rollout files each second. A full metadata sweep every minute catches missed file discoveries.
• Every 30 seconds, a watcher pass schedules work, checks sources that cannot report file changes, and retries interrupted imports.
• New transcript writes move ahead of the remaining scheduled checks. The optional Codex subagent message recovery runs at most once, after pending imports finish.
• Watched sources also get a full check every 15 minutes, even when no file change arrives.
• A source that keeps finding nothing new is checked every 5 minutes instead.
• A failed import waits before it retries, starting at 1 minute and growing to at most 30 minutes.
• A file whose last import took a while waits three times that import’s duration, at most a minute, before its next import. Other changed files of the same source import at their usual time.

Imports run one at a time, so two sources never write to the archive at once. Activity that arrives during an import waits and runs next, ahead of routine checks.

After you change the source list

The watcher picks up a changed source list within 30 seconds, starts watching the new folders, and checks the added sources for sessions it missed. You do not need to restart it.

Scheduled tasks

Besides importing sessions, the watcher:

• refreshes the search and conversation list indexes after imports;
• backs up memories from your harnesses every 15 minutes;
• refreshes the cloud agents turned on in Settings → Imports → Cloud agents: Cursor cloud agents every minute and the others every six hours;
• reinstalls recall integrations that disappeared, every 15 minutes, and runs the shared MCP host that agent sessions’ recall tools connect to;
• samples plan limits and activity from supported signed-in harness CLIs every 15 minutes while the Mac is awake, when usage tracking is on;
• runs sync at the interval you set, when sync is set up; and
• sends the notifications you turned on.

The 15-minute tasks run beside imports, so an import that is ready never waits for them. Import and capture workers run at background priority, below the app, the shared MCP host, and Stats.

Starting the watcher does not turn on sync, usage tracking, or cloud imports. Notifications are on by default for what needs you; hansard notify status shows their kinds and destinations. Usage tracking is a setup choice; change it with hansard config setup --track-usage or hansard config setup --no-track-usage. Starting the account router, or turning on automatic account switching, turns usage tracking on when no Track usage setting has been saved, because routing depends on current usage. A saved setting, on or off, is kept. Each sample also records the router accounts’ usage, including accounts a routing rule holds, and applies the routing rules again.

Usage samples appear on the Accounts page, where each account’s summary separates plan limits from activity counts. Select an account to open the charts on the Usage history tab. Codex, Claude, Antigravity, Devin, Grok Build, and Cursor report plan limits. OpenCode reports 30-day session, message, and token counts. Sampling never sends a prompt to a model.

Sleep pauses sampling. Sampling resumes when the Mac wakes, but samples missed during sleep cannot be filled in later.

Common questions

Does Hansard keep conversations after an agent deletes them?

Yes. Each import keeps a copy of the harness’s original files beside the readable conversation, so it stays in your archive after Claude Code’s 30-day cleanup or another harness’s retention removes it. The watcher has to import a session before the harness deletes it. See Harness settings for how long each harness keeps its history.

How soon does a new session appear in the archive?

Usually within seconds. The watcher imports once a source has been quiet for 2 seconds, and waits at most 10 seconds while a harness keeps writing. Sources that cannot report file changes are checked every 30 seconds. A long conversation whose last import took a while can wait up to a minute.

Does the watcher start when I sign in to my computer?

When you turn it on. hansard init offers login startup, and hansard watcher login enable turns it on later. Check it with hansard watcher login status.

Troubleshoot delayed imports

Start with the watcher’s state and its live log:

hansard status
hansard watcher status
hansard watcher logs --follow

Then compare the watcher with a direct import of the same source:

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 file watches:

hansard watcher restart

The log line tick skipped: previous tick still running means a watcher pass was still running when a second 30-second check came due, and tick finished after N skipped intervals follows when that pass ends and names the pass’s three slowest steps. It usually points to a large import backlog or a slow source, not a stopped watcher. New activity stays queued and moves ahead of routine checks when the current import ends. Follow the log to find the source that is still running, then run hansard doctor to check dependencies and source availability. Its watcher ticks check names the steps that took the most time in recent passes.

A source that reports no progress for 60 seconds is stopped and tried again later, with a longer wait after each failure, while the other sources keep importing. An import of one source also stops after 10 minutes, or after 30 minutes for Cursor and cloud sources. These limits, the 10-minute stall check of sync uploads and receives, and the time limits on the watcher’s indexing, Stats, labeling, maintenance, search by meaning, and summary work count only time the computer is awake. Work that a sleep interrupts continues after the computer wakes instead of being stopped as stalled. While sources wait, the app’s import status names the import that holds the import lock. On macOS, history in a folder the Hansard app may not read waits until you allow it; check Settings → Imports → macOS access.

Run without the watcher

To stop all background work, turn off the sign-in item and stop the watcher:

hansard watcher login disable
hansard watcher stop

The archive stays usable. You can still run imports, indexing, memory backup, and sync yourself.