# Configuration > Change Hansard's settings in the app or with hansard config, and look up common keys and environment variables. 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](https://www.hansard.dev/reference/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**](https://www.hansard.dev/imports/supported-sources/#cloud-agents-in-the-app), [**Search**](https://www.hansard.dev/guides/search/#search-by-meaning) (**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**](https://www.hansard.dev/imports/browser-capture/), and [**Maintenance**](https://www.hansard.dev/reference/maintenance/#check-health-in-the-app). **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**](https://www.hansard.dev/guides/running-agents/#automatic-pause), 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](https://www.hansard.dev/guides/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](https://www.hansard.dev/guides/continue/#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 ```sh hansard config show hansard config show --json hansard config path hansard config get storage.root ``` Secret values are masked. `hansard config get --reveal` prints the raw value; use it only where the terminal output is safe. ## Change a value ```sh 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: ```sh 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** ```sh hansard config sources edit ``` **Scripted** ```sh 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 `/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](https://www.hansard.dev/reference/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.`, `notifications.channels.`, `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](https://www.hansard.dev/sync/teams/) 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](https://www.hansard.dev/reference/cli/#interactive-mode-and-tab-completion) 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](https://www.hansard.dev/imports/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](https://www.hansard.dev/reference/terminals/#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](https://www.hansard.dev/reference/maintenance/#review-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](https://www.hansard.dev/guides/classification/#label-from-similar-conversations). | | `summaries.enabled` | `false` | Summarize ended conversations from the watcher, for **Continue from summary** and recall. See [Continue from a summary](https://www.hansard.dev/guides/continue/#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](https://www.hansard.dev/privacy/redaction/). | | `HANSARD_HOME` | Use another Hansard home instead of `~/.hansard`. | | `HANSARD_WEB_PASSWORD` | Password for a [hosted viewer](https://www.hansard.dev/sync/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**](https://www.hansard.dev/guides/stats/#compare-models-on-the-analysis-tab) 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](https://www.hansard.dev/guides/agent-integrations/#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.