# Install the app

> Download Hansard for macOS or Windows and set up your archive without a terminal.

Installers for macOS and Windows, with their checksums, are listed at [Install the app](https://www.hansard.dev/getting-started/download/).

Previous releases

The desktop app includes everything it needs to run. You do not need Node.js,
npm, a terminal, or a Hansard account. It supports macOS 13.5 or newer and
64-bit Windows 10 or newer. Links that lead outside the app open in your
default browser.

## Install on macOS

1. Download the installer above. If downloads for both Apple silicon and Intel
   are listed, choose **Apple menu → About This Mac** to see which chip your Mac
   has.
2. Open the `.dmg` file and drag **Hansard** into **Applications**.
3. Open Hansard from **Applications**, then eject the disk image.

Open the app from Applications, not from the disk image. When Hansard runs from
the disk image, setup cannot turn on automatic archiving.

The [menu bar dashboard](https://www.hansard.dev/guides/menu-bar/) provides quick access to
running agents, memory, account usage, and import status.

### Open Hansard for the first time on macOS

The first time you open it, macOS asks you to confirm that you want to open an app
downloaded from the internet. Choose **Open**.

If macOS blocks the app:

1. Try to open Hansard once, then close the warning.
2. Open **System Settings → Privacy & Security**.
3. In the security section, choose **Open Anyway**, then confirm.

### macOS login items and folder access

When the app archives automatically, it starts the watcher at login through
its own login item, so **System Settings → General → Login Items** lists it as
Hansard, and macOS may show a notice that Hansard added a background item.

The watcher reads Documents, Desktop, Downloads, cloud storage folders, other
apps' data, and external and network drives only where macOS allows the
Hansard app, so macOS never asks about them in the background. To see what
Hansard may read and answer the questions left, open **Settings → Imports →
macOS access** and select **Ask macOS**.

macOS has no question for **Data from other apps**, such as Warp's history,
and keeps no answer for it that the watcher could use. That row and every
folder you declined offer **Open System Settings** instead, which opens the
pane that holds the switch: Full Disk Access for other apps' data, and Files &
Folders for a declined folder. Turn on Hansard there. The row updates when you
return to Hansard. The watcher reads with Full Disk Access after it next
starts, for example after a restart or an app update.

## Install on Windows

1. Download **Windows x64** above.
2. Open the installer and follow its steps. It installs for your Windows user
   without administrator access.
3. Open **Hansard** from the Start menu.

## Set up your archive in the app

On first launch, Hansard opens a guided setup that fills the window, with one
settings card for each step beside a live demo of what it changes. It creates
the archive on this computer, then walks through the rest of the app one page
at a time. Select **Continue** to move on, **Back** to return, or a dot at the
top to revisit a page you have already seen.

1. **Welcome** and **Pick a look**: choose a **Mode** (System, Light, or Dark),
   a **Sidebar theme**, and whether to **Color the session list**.
2. **Find your history**: Hansard lists the agents that have history on this
   computer and how much each holds. Select a tile to leave that agent out.
   Agents that are installed but have no history yet are grouped under **Watch
   new agents**, so their new conversations are saved as they start. Cloud
   agents already signed in on this computer, such as Claude Code cloud and
   Codex cloud, have their own switches, and their history imports too unless
   you turn them off. Under **How far back**, choose **30 days**, **90 days**,
   or **All history**. Original files stay in place. When an agent deletes old
   conversations on its own, as Claude Code does after 30 days by default,
   **Keep history for 10 years** raises its `cleanupPeriodDays` setting and
   saves a backup of the previous settings file. Hansard keeps its own copy
   either way.
3. **Give your agents a memory**: Hansard lists every coding agent it found
   and adds Hansard to each one you leave on: the Hansard MCP server, the
   recall skills (recall, deep recall, continue-from, and memory
   unification), and a session-start hook. **What each agent gets** lists
   them. **Agents you install later** gives agents installed afterward the
   same tools as soon as Hansard finds them. **Skills and plugins from your
   other agents** lets each agent use what the others installed. Nothing is
   added until the import starts.
4. **What leaves this computer**: **Redact common secrets** hides API keys and
   tokens in the searchable copy; originals stay unredacted.
   **Claude Code activity** keeps Claude Code's timing and errors on this
   computer. **Track plan usage** asks your providers for plan limits, and
   **Check for updates** asks npm or hansard.dev for new releases. **Link
   icons** fetches icons from sites linked in conversations you open. The
   watcher starts at login wherever the install supports it.
5. **Make it yours**: a tile for each optional feature. **Search by meaning**,
   **Agent messaging**, **Helper agents**, and **Keep history** have a switch.
   Features that need storage, a sign-in, an install, a pairing, or a token,
   such as Personal Sync, remote access, labeling, web chats, Slack, the
   account router, and Teams, offer **Set up**, which adds that feature's
   guide after the core steps.
6. **Your work setup**: the switches that [pause idle agents and resume them](https://www.hansard.dev/guides/running-agents/#automatic-pause)
   where they ran: **Pause idle agents**, **Pause under memory pressure**,
   and **Resume for requests**.
7. **macOS access**, in the Mac app: macOS asks before an app opens folders
   such as Documents, Desktop, Downloads, cloud storage folders, or other
   apps' data. When the history you chose lives there, select **Ask macOS**
   to answer each question now, one at a time, so the import never stops to
   wait for you. **Data from other apps** has no question: select **Open
   System Settings** and turn on Hansard under Full Disk Access. Hansard skips
   a folder you do not allow until you allow it in **System Settings → Privacy
   & Security**.
8. **Build your archive**: Hansard shows how much history it found and how
   much free space the archive needs. Under **Recover older history**, it
   offers the recoveries it detected, such as Claude Code files that Claude Code
   deleted, older Antigravity or Windsurf conversations, and Cursor models and
   token counts. Select **Start import**. Conversations appear on screen as they
   are archived. The import keeps running in the background, so you can
   continue setup while it works. Meanwhile **Stats** shows a first look at
   your Claude Code and Codex history, read straight from their files.

The remaining pages configure a running archive. Each one offers
**Set up later**:

- **Your agents**: under **Agents working together**, **Message board** lets
  Codex and Claude Code sessions message each other, and **Subagents in other
  agents** lets them start a subagent in another installed coding agent, such
  as Grok Build or Antigravity. Claude Code asks before it reads each message
  from another session unless **Accept messages in Claude Code** is on.
  **Permission modes** says which mode each agent starts in when Hansard
  continues a session. Each agent uses its configured permission settings.
  **Change permission modes** chooses an explicit override for sessions
  launched through Hansard. Nothing is written until **Continue**, which
  applies every choice at once; **Set up later** leaves the agents as they
  were.
- **Personal Sync**: copies the archive to a folder or bucket you own, with
  the same step-by-step storage walkthroughs as
  [Settings → Personal Sync](https://www.hansard.dev/sync/personal-sync/).
- **Remote access**: lets your other computers and a phone reach this one.
- **Label conversations**: labels new conversations by the kind of work they
  were.
- **Web chats**: walks through adding the browser extension to Chrome, Brave,
  Edge, or another Chromium browser, pinning it, pairing it with Hansard, and
  turning on its sites, then waits for the first saved chat.
- **Slack**: creates the Slack app, connects its bot token, picks a channel,
  and sends a test post.
- **Account router**: chooses how Claude Code and Codex move between
  accounts. The router can also hold Antigravity, Devin, Grok, Kimi, and Meta
  accounts.
- **Teams**: creates or joins a Team.

Each page after **Your agents** is a feature's guide, and it appears only when
you chose **Set up** for that feature on **Make it yours**. **Finish** applies
the choices you made along the way.

Steps you leave for later appear at the top of **Settings** as a
**setup steps left** card. Select it to resume at the first one, or dismiss it.
When setup opens another page, such as **Accounts** for the account router, or
when you select **Leave setup**, a **Back to setup** item in the title bar
returns to the step you left. It stays until you finish setup or
dismiss it, and waits while the **setup steps left** card shows in Settings.
In a browser session started with `hansard web`, the same pages are available
at `/onboarding`.

The first time you open a page such as **Accounts**, a project overview,
**Settings → Imports**, or **Settings → Personal Sync**, a short guide
introduces it, with rows that sign you in or turn a feature on in place. A
guide you finish or skip does not come back on its own. **Settings → About →
Guides** shows any of them again.

If you have a ChatGPT, Claude.ai, or Gemini export, see
[ChatGPT and Claude.ai exports](https://www.hansard.dev/imports/web-exports/) once the archive
exists.

If Hansard is already set up on this computer, for example with the CLI, the app
skips setup and opens your existing archive.

## Update the app

macOS builds with the native updater check on launch and hourly while open. The
updater runs only in an app signed with Hansard's Developer ID, such as the
installer from this page, and checks that signature again before it downloads
an update. A locally built app updates through the installer download. When a
newer version is available, **Settings → About** offers **Update and
restart**. The update button above **Settings** in the dock opens that page and
starts the same update. Hansard downloads and verifies the update, replaces the
app, and relaunches. Background archiving from the app resumes automatically.
**Settings → About → Check now** checks immediately.

When a restart would stop work, **Restart to update?** lists it first: agent
turns, Deep Recall, classification, and terminals running a program. Agents
idle at their prompt are listed separately, and they close when Hansard
restarts. Select an item to open its conversation or terminal.

- **Restart When They Finish** keeps the verified download ready and restarts
  once the listed work ends. **Settings → About** lists what it waits for,
  with **Stop waiting**.
- **Stop Work and Restart** stops the listed work and restarts now. The next
  start resumes interrupted turns, as described in
  [Resume after a restart](https://www.hansard.dev/guides/continue/#resume-after-a-restart).
- **Close and Restart** appears when only idle agents are listed.

You can resume the conversations of closed agents later. Agent sessions whose
recall servers run from the app move to the new app on their own. To see what
runs from the installed app, run `hansard app processes`.

On Windows, **Settings → About → Check now** checks for a newer installer.
Updates use a manual download. Wait for imports and agent runs to finish,
quit Hansard, and run the newer Windows installer. It keeps your archive and
settings. Windows does not use the macOS automatic updater.

The published 0.5.5 app predates the updater. Upgrade it manually once to get
this feature. Older shells and releases without signed updater archives keep
the installer download flow:

1. Wait for any running import to finish, then quit Hansard.

2. If you also use the CLI, stop the watcher:

   ```sh
   hansard watcher stop
   ```

3. Download the new version from this page, open the disk image, and drag
   **Hansard** into **Applications**. Replace the existing copy.

4. Open Hansard. If the **Not archiving new conversations** alert appears at
   the top of the window, select **Start**.

After an update, Hansard shows **New in Hansard** once, as a short sequence
that shows each highlight in turn and the setup steps that apply to this
computer. It runs the steps you chose only at **Finish**, and a step that fails
shows its reason beside **Run again**. **Settings → About** opens it again.

After an update, the watcher also brings older archived conversations up to
the new release's files in the background. See
[Refresh after updates](https://www.hansard.dev/reference/background-work/#refresh-after-updates).

Your archive and settings are stored in `~/.hansard` on macOS or
`%USERPROFILE%\.hansard` on Windows, outside the app, so an
update keeps them. An update replaces the whole app. The CLI, if you installed
it with npm, updates separately.

## When to use the CLI instead

The app covers reading, searching, stats, memories, and settings. Install the
[CLI](https://www.hansard.dev/getting-started/installation/) as well when you want to:

- add [recall](https://www.hansard.dev/guides/agent-integrations/) to an agent from its own
  terminal or a script;
- import all history after setup, or import from cloud agents such as Devin or
  Jules;
- script Hansard, or run checks such as `hansard doctor`;
- use Hansard on Linux, where the app runs in a browser.

The CLI and the desktop app share one archive. With the CLI installed, `hansard app`
opens the desktop app. If the app is missing, `hansard app` installs it when your
CLI build has a download configured. To install a disk image you downloaded,
run:

```sh
hansard app install --from ~/Downloads/Hansard-macos-arm64.dmg
```

On Windows, pass the downloaded installer instead:

```powershell
hansard app install --from "$env:USERPROFILE\Downloads\Hansard-windows-x64.exe"
```

`hansard app --no-fallback` only opens an app that is already installed.
`hansard web` opens the same interface in your browser.