Configuration

Hansard stores its settings in config.json in the Hansard home. Change them in Settings in the app or with hansard config. Both write through the same checks, so avoid editing config.json by hand.

App

Settings

CLI

hansard config

Use Settings in the app

Open Settings from the bottom of the dock, or press Command-comma on a Mac. Type in Search settings to find a setting by name, or by its configuration key, such as archive.autoRefresh.

Group	Section	What it controls
Personal	General	This device’s name, your name, whether imported web chats show in Sessions, what opens when you select a project, whether Stats count subagent runs, dictation, and the Command line tool, which installs, updates, or removes the hansard command where the app can manage it.
	Appearance	Theme, the sidebar theme (a preset or your own colors, which also color the activity heatmaps, and whether it colors the session list), timestamp format, time gaps and context cards in conversations, and how many conversations and memories each sidebar folder shows.
	Notifications	Which kinds of notification Hansard sends, where they go (macOS, cmux, a paired phone), when they wait (in the background only, Follow Focus, quiet hours, and a burst limit), and Send a test notification.
	Shortcuts	Keyboard shortcuts.
Archive	Imports	The Background import status, Pause search updates, Incomplete runs, which agents Hansard imports (Automatic or Custom) and the Instinct number, Cloud agents, Search (Search by meaning, Screenshot search, Automatic graph builds, and Background work, whose Pause holds indexing, graph builds, automatic labeling, and summaries), the Look-back window, Save screenshots and PDFs, Import older history, Import export… for ChatGPT, Claude.ai, Gemini, and Gemini Notebook / NotebookLM exports, the Browser extension, and Maintenance. Importer version appears when the watcher runs a different copy of Hansard.
	Projects	Your projects, path-based rules, and built-in agent folders.
	Portfolios	Display groups of related projects.
	Classification	Whether and when conversations are labeled, Summarize conversations after they end, the provider and model, extra labels, and manual runs.
Agents	Coding agents	Hansard in each agent, which adds, repairs, or removes Hansard’s tools in each coding agent, Automatic setup, Plan usage, and a read-only view of each agent’s memory, transcript cleanup, model, and permission settings on this device.
	Handoff & helpers	Which harnesses appear in Continue in and their default permissions, Resume after a restart under Interrupted turns, Take over conversations running elsewhere under Running elsewhere, Pause and Resume, the agent message board, helper agents, and Send Claude Code activity to Hansard and Activity listener under Activity.
	Coordinator	The harness, model, reasoning effort, Codex speed, and helper budget every project’s coordinator uses.
Sharing	AI assistants	Connecting ChatGPT, Claude, or another hosted assistant to this Mac. See AI assistants.
	Privacy & Sharing	Keep unredacted copies and a Sharing summary of the features that can send conversations off this computer, with what each one sends.
	Personal Sync	This computer’s Personal Sync backup and its Storage copies.
	Remote access	Running agents on your other computers and letting them run work on this one. See Run agents on your other computers.
	Slack	Posting, bot tokens, posting rules, and the daily digest.

About, below the groups, shows the running version and update status, What’s new for this version, the Guides that introduce each page, this device’s name and your name, and where each kind of preference is stored.

Some values have no control in the app. Change those with hansard config.

Inspect configuration

hansard config show
hansard config show --json
hansard config path
hansard config get storage.root

Secret values are masked. hansard config get <key> --reveal prints the raw value; use it only where the terminal output is safe.

Change a value

hansard config set imports.defaultSinceDays 90
hansard config set sync.intervalMinutes manual
hansard config set index.paused true
hansard config unset notify.slack.botToken

true and false become booleans, numbers become numbers, and valid JSON is parsed. Everything else is stored as a string. After changing storage, run hansard watcher restart so the watcher picks up the change right away. The watcher applies a changed source list within 30 seconds on its own.

Reopen setup choices

hansard config setup revisits the preference steps of hansard init without importing anything:

hansard config setup
hansard config setup --watch-sources codex-cli,cursor --default-since-days 90
hansard config setup --sync-interval-minutes manual --no-autostart
hansard config setup --no-track-usage
hansard config setup --no-agent-collaboration

Choose sources

Interactive

hansard config sources edit

Scripted

hansard config sources set codex-cli,cursor,cline
hansard config sources enable antigravity-cli
hansard config sources defer cursor
hansard config sources disable claude-cowork
hansard config sources reset

Hansard keeps three source lists: sources to backfill, sources the watcher follows, and deferred sources.

Command	Effect
set	Replaces the watcher list and keeps the backfill list.
enable	Adds a source to both backfill and watching.
disable	Removes a source from both.
defer	Keeps watching new conversations but skips the source in hansard import --source all backfills.
reset	Restores the defaults, clears deferrals, and turns on discovery of new sources.
add, remove	Older names for enable and disable.

--source and --sources on hansard import override these lists for that run only.

Common keys

Key	Default	Effect
storage.root	~/.hansard/data	Where the archive lives. Hansard writes to <root>/hansard.
device.name, person.name	This computer and your name	Labels recorded on every conversation and used by sync. A new name is stamped onto this computer’s archived conversations in short batches; the watcher’s archive maintenance finishes a pass that stopped, and Settings shows a rename conversations still owe.
imports.defaultSinceDays	30	How far back each watcher pass looks.
imports.autoDiscoverSources	true	Watch newly detected harnesses automatically.
index.paused	false	Keep importing but stop updating search.
artifacts.enabled	false	Copy screenshots and PDFs referenced by tool calls into the archive.
archive.format	2	2 keeps each conversation’s Markdown gzip-compressed (*.conversation.md.gz), the events of conversations above 1 MiB as event records (*.event-record.jsonl) and the views of conversations with more than 1000 messages or a view above 1 MiB only as pages (*.view-pages/), and updates the transcripts of growing conversations in place, writing only the lines that changed at their end. Earlier Hansard releases cannot read all of these forms, so imports keep writing format 1 while such a copy may open the archive; hansard config set archive.format 2 names those copies. A 1 saved by a release before the default changed reads as 2; hansard config set archive.format 1 keeps format 1.
archive.rawStorage	whole	chunked keeps the snapshot of a shared SQLite store larger than 1 MiB as compressed 1 MiB chunks that later versions share; every other raw source stays whole-file. Imports chunk only while every device and every copy of Hansard here reads chunked raw storage, every installed copy waits for it before uploading a chunked snapshot, and no archive-files sync target exists. An upload carries a chunked snapshot only while the format reads ready for that Personal Sync space, and the first one makes the space require it for good; hansard config set archive.rawStorage chunked names what waits.
archive.derivationCache	true	Keep a cache of what the watcher derived from each conversation whose last message is at most six hours old, so the next import of a growing conversation derives only its new messages. The caches stay within 1 GiB in all under the Hansard cache folder and are skipped when the volume would keep less than 2 GiB above the storage floor. false turns it off.
archive.autoRefresh	true	Refresh older conversation data and supported raw parses after updates. Eligible storage conversion waits for compatible readers. Refresh after updates in Settings → Imports → Maintenance controls the same value. See Background work.
sync.sessionPayload	markdown	What Personal Sync uploads carry of each conversation. full uploads every file; markdown leaves conversation.md out, since receivers render it; index also leaves out the transcript of a conversation every receiving device re-parses from its raw files and that a parity receipt shows derives from them. conversation.md is left out only while the space’s Conversations without Markdown format reads ready, and a transcript only while Index-only conversations reads ready too, either only while every copy of Hansard installed here has the code that leaves them out; the first upload that leaves one out makes the space require it for good. hansard config set sync.sessionPayload index names what waits.
privacy.revealCache	true	Keep the original form of each message redaction changes, so hansard show --unredacted and hansard redact reapply can rebuild a conversation as it was before redaction. A conversation redaction leaves unchanged keeps nothing.
privacy.webChatsDefaultScope	all	local hides imported web chats from Sessions by default.
notifications.enabled	true	Whether Hansard notifies you at all. notifications.categories.<kind>, notifications.channels.<destination>, notifications.quietHours.enabled, .start, and .end, and notifications.burst.max and .minutes set the rest, as Settings → Notifications does; hansard notify status prints them with each destination’s last delivery, and hansard notify test sends a test notification.
privacy.teamConversations	hidden	shown keeps conversations received through a Team in Sessions, Stats, and Graph. They always appear in Teams.
web.includeSubagentSessions	true	Count subagent sessions in Stats.
web.linkFavicons	true	Fetch icons for links shown in conversations from the linked sites. Link icons in Settings → Appearance sets the same value.
updates.checkOnStartup	true	Check the npm registry for a newer release once a day. Check for updates automatically in Settings → General sets the same value.
updates.whatsNew	true	Show New in Hansard once after each update. hansard whats-new still works when it is off.
cli.interactive	true	Open the interactive mode when hansard runs with no command in a terminal. false prints the command list instead.
imports.cloudSources	[]	Cloud agents turned on in Settings → Imports → Cloud agents, which the watcher refreshes every six hours, and Cursor cloud agents every minute.
imports.instinctHandle	""	Your Instinct number with its country code. Empty keeps Instinct capture off. Instinct number in Settings → Imports → Agents sets the same value.
orchestrate.resumeAfterRestart	true	Resume turns that a quit, update, or crash cut short when the app starts again.
orchestrate.takeOverElsewhere	true	Stop a Claude Code or Codex conversation’s copy in another terminal app before resuming or messaging it in Hansard. See Take over a conversation running elsewhere.
storage.limits.minFreeBytes	2 GiB	Free space Hansard leaves on the disk when it copies original files and upload payloads.
storage.historyRetention.enabled	false	Allow pressure recovery to expire eligible historical checkpoints after cleanup cannot make room for an exactly sized write. Current evidence, pins, readers, and pending uploads stay protected. This does not enable checkpoint capture.
storage.historyRetention.policy	1 day / 7 days / 30 days / 10 GiB	allForMs, hourlyForMs, retainForMs, and maxBytes control retained checkpoint density and storage. See Snapshot history.
storage.limits.totalBytes, storage.limits.totalObjects	null	Optional allowances for the storage Hansard accounts for. storage.limits.categories sets separate allowances for evidence, history, staging, and pendingUploads.
classify.enabled	false	Allow classification after an explicit opt-in. Existing saved choices remain unchanged.
classify.auto.enabled	false	When enabled, classify settled conversations from the watcher every 15 minutes.
classify.auto.staleAfter	7d	Idle time before a conversation is classified automatically.
classify.backend	auto	auto, local-model (Ollama), claude-cli, codex-cli, anthropic, openai, or jev (TypeSafe).
classify.neighbors.enabled	false	Answer optional label requests from the most similar labeled conversations when they agree with the model often enough. Needs search by meaning. See Label from similar conversations.
summaries.enabled	false	Summarize ended conversations from the watcher, for Continue from summary and recall. See Continue from a summary.
summaries.backend, summaries.model	codex-cli, gpt-6-luna	The backend that writes summaries, codex-cli, claude-cli, openai, or anthropic, and the model it uses.
collector.enabled	true	Receive Claude Code timing and errors at localhost:4318 while the watcher runs. Claude Code activity defaults on in desktop setup and hansard init. Accepted setup adds local reporting settings to Claude Code. Off writes nothing to those settings. Existing exports elsewhere stay unchanged. Send Claude Code activity to Hansard and Activity listener in Settings → Handoff & helpers also control it.
dictation.backend	auto	auto, apple, whisper, openai, command, browser, or off.
orchestrate.messaging.mode	same-project before setup	Agent messaging scope: off, same-project, or all-local. Setup asks with no answer selected. Skipping or hansard init --yes alone saves off.
orchestrate.messaging.relatedConversations	true	With search by meaning on, list up to three earlier conversations close to a new Codex or Claude Code session’s first prompt.
orchestrate.messaging.historyNotes	true	After a tool call that names a file with a reverted, failed, or later fixed change, or that runs a test failing the way an earlier fixed failure did, add that history with anchors to past conversations, once per conversation. Needs messaging on.
orchestrate.delegation.mode	same-project before setup	Helper agents: same-project or off. Setup asks only after messaging is On, with no answer selected. Skipping or hansard init --yes alone saves off.
orchestrate.coordinator.provider	empty	Harness for every project coordinator: codex or claude_code. Empty uses the first available, Codex then Claude Code.
orchestrate.coordinator.model, orchestrate.coordinator.effort	empty	Coordinator model and reasoning effort. Empty leaves the choice to the harness’s own configuration.
orchestrate.coordinator.serviceTier	empty	Codex coordinator speed: default (Standard), priority (Fast), or ultrafast. Empty follows Codex’s own setting.
orchestrate.coordinator.maxAgents	32	Helpers one project’s coordinator may start, finished ones included, from 1 to 100.
integrations.autoSync	true	Reinstall recall files and MCP entries that disappear. Keep integrations in sync in Settings → Coding agents sets the same value.
integrations.autoInstall	true	Install recall in agents first detected after setup. Add Hansard to agents you install later in Settings → Coding agents sets the same value.
sync.intervalMinutes	30	Sync cadence for a generic remote target, and the default for new Teams. manual or 0 turns it off.
sync.profileState.enabled	true	Share settings, usage, and classification results through Personal Sync.
notify.slack.enabled	false	Post to Slack.
stats.sdkJobs.forceJob, stats.sdkJobs.forceDelegated	[]	Repositories or paths whose SDK sessions always count as batch jobs, or always count as delegated work.
stats.probeSessions.forceProbe, stats.probeSessions.forceSession	[]	Repositories or paths that always or never count as machine probes.
projects.harnessDefaults	true	Group projectless harness folders into a harness portfolio.

hansard help config lists more keys, including the orchestrate.* permission defaults and the dictation.* engine options.

Files and environment variables

Name	Purpose
~/.hansard/config.json	Settings. hansard config path prints the active path.
~/.hansard/redaction.yaml	Redaction rules. See Redaction.
HANSARD_HOME	Use another Hansard home instead of ~/.hansard.
HANSARD_WEB_PASSWORD	Password for a hosted viewer.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY	Storage credentials for sync when you do not pass them as options.
HANSARD_SLACK_BOT_TOKEN, SLACK_BOT_TOKEN	Slack bot token when notify.slack.botToken is not set.
DEVIN_API_KEY, JULES_API_KEY, CURSOR_API_KEY, FACTORY_API_KEY, GH_TOKEN, GITHUB_TOKEN	Credentials for cloud imports.
ANTHROPIC_API_KEY, OPENAI_API_KEY	API classification backends, and OpenAI dictation.
TYPESAFE_API_KEY, TYPESAFE_BASE_URL	The Jev classification backend’s API key and optional endpoint override.
ARTIFICIAL_ANALYSIS_API_KEY	The Artificial Analysis Intelligence Index on the Stats Analysis tab. It takes precedence over a key saved there.
HANSARD_WORKER_MAX_OLD_SPACE_MB, HANSARD_WEB_MAX_OLD_SPACE_MB	Memory limits for import workers and the viewer, from 256 to 4096.
HANSARD_REMOTE_CONTROL	0 turns off remote control in the CLI and the app.
HANSARD_MCP_HOST, HANSARD_MCP_PORT	off runs each agent session’s recall server in its own process instead of the shared MCP host; the port sets the host’s loopback port (default 7839).
HANSARD_NO_WHATS_NEW	1 turns off the New in Hansard dialog and the note after the first command of a new version.
HANSARD_INTERACTIVE	0 makes a bare hansard print the command list instead of opening the interactive mode.
HANSARD_HARNESS_MODEL_MENUS	0 keeps model menus from starting agent CLIs or reading agent stores to list their models.

After changing watcher, index, storage, or sync settings, run hansard status to confirm the result. Run hansard doctor when a source is missing or an integration looks unhealthy.