Install the CLI

The CLI provides the hansard command and the browser version of the app. Use it in terminals and scripts, and to connect Hansard to your coding agents. To have a coding agent install and set up Hansard for you, see Set up with an agent. For the desktop app, which includes Node.js, see Install the app.

Requirements

• Node.js 22.12 or newer (or 20.19 or newer on Node.js 20), with npm. Node.js 21 is not supported. Check your version with node --version.
• macOS, Linux, or Windows.
• Free disk space for your history. Setup measures it before importing.

On macOS and Linux, run the commands in a terminal. Linux uses the browser app through hansard web. Login startup uses a systemd user service on Linux and a LaunchAgent on macOS. If your Linux system has no systemd user session, keep hansard watcher start --foreground running in a terminal or your service manager.

On Windows, run the commands in PowerShell or Command Prompt. Hansard reads provider stores from their Windows locations, including %APPDATA%, and honors provider home overrides such as CODEX_HOME and CLAUDE_CONFIG_DIR. SQLite and ZIP readers are bundled; separate sqlite3 and unzip programs are not required for imports. The default Hansard home is .hansard under HOME, or USERPROFILE when HOME is unset. With neither variable set, Hansard uses the operating system home. Set HANSARD_HOME to the absolute path of another local directory, or a path under ~/, to use it instead. Login startup uses a current-user Scheduled Task with no administrator privileges.

Windows x64 desktop builds include Node.js and use a per-user installer. See the download page for available installers and their signing status. To install one you downloaded, run hansard app install --from .\Hansard-windows-x64.exe.

Tested platforms

Verified identifies the completed checks named in the table. Preview means the implementation is available, with release acceptance still incomplete. Planned release means a build target exists but no installer is published.

Platform	CLI	Desktop app	Browser extension
macOS Apple silicon	Preview	Verified signing and notarization	Preview
macOS Intel	Preview	Planned release	Preview
Windows x64	Preview with recorded native tests	Preview, unsigned installer	Preview
Linux	Preview	No native installer	Preview

The automated test configuration covers Linux with Node.js 20, 22, and 24, plus macOS and Windows with Node.js 24. Package installation trials also cover all three operating systems. These configured checks do not establish a passing run for every release or a separate Intel CLI result. Recorded native Windows trials cover an earlier release, so the current CLI remains labeled preview.

The Apple silicon download has verified signing and notarization. Independent clean-machine installation and signed updates between two versions remain pending. The Windows download is an unsigned preview. Intel has a desktop build target but no published download. Check Install the app for current artifacts. On Linux, use the CLI and browser app.

The extension targets Chromium browsers with Manifest V3 and Chrome 109 or newer. Its preview status applies to each operating system above. Provider capture checks do not establish complete browser and operating-system coverage. See Browser capture for source-specific limits. Firefox and Safari extension packages are not available.

Install the package

npm install -g hansard
hansard --version

Install the package globally. Your agents run the hansard command when they recall past conversations, so it must be on your PATH. If your shell cannot find hansard after installing, add npm’s global bin directory to your PATH instead of installing a second copy.

Installing the package does not set anything up. Run hansard init next.

Avoid running setup through npx, pnpm dlx, or bunx. Those commands can run a cached copy that later disappears, leaving agent integrations or login startup pointing at it. hansard init --dry-run names the agent files setup would change and warns when their launcher comes from a temporary package cache.

Run setup

To preview setup without writing anything, run:

hansard init --dry-run

The preview lists the history Hansard found and its size, estimates the disk space the archive needs, and shows every change setup could make, including each agent file it would change. When you are ready, run the setup wizard:

hansard init

To choose the initial history window, use hansard init --since 30d for the past 30 days or hansard init --since all for all available history. The option also accepts hours, minutes, and ISO dates. This selects the initial import window. The setup wizard reviews ongoing archiving separately.

In checklists, use the arrow keys to move, Space to select, and Enter to confirm. The wizard asks, in order:

1. Where to keep the archive, ~/.hansard/data by default, and names for this device and for you. Hansard records these names on archived conversations and uses the device name for sync.
2. Whether to redact common secrets in the searchable copy. Redaction is on by default. The original copies are kept unredacted.
3. Which sources to import now and which to watch for new conversations. Hansard scans your harness folders first and shows how much history each one has.
4. Whether agents in the same project can message each other and start helper agents. Both questions start unanswered. Helpers require messaging. Skipping or --yes alone keeps both off. A message can announce that an API is ready for tests. A helper can review a change.
5. How Hansard runs: background archiving, plan usage, local meaning search, labeling, update checks, and link icons. Claude Code activity is on by default. It reports timing and errors to Hansard on this Mac. Accepted setup adds a few lines to Claude Code’s settings. Turning it off writes nothing to those settings. Existing exports elsewhere remain unchanged.
6. Which extras to turn on: recall in your agents, copying referenced screenshots and PDFs into the archive, and the interactive mode that opens when you run hansard with no command (on by default).
7. Whether to import your existing history now and connect Slack notifications.
8. Whether to sync to Cloudflare R2, Amazon S3, or another S3-compatible store. Setup offers this only after the local archive is ready. To add sync later, run hansard sync configure.

Before importing, setup compares the size of your history with the free space at the archive location. The estimate includes the original copies, the searchable archive, and a reserve of free space. If there is not enough space, or the space cannot be checked, the import does not start. A size shown as “at least” comes from a scan that stopped early in a very large folder.

When setup finishes, it prints commands for opening Hansard and checking status. Imports continue in the background.

Run setup again

Running hansard init again offers to keep, edit, or reset your saved source choices, then shows one review before saving. To change preferences without importing again, run hansard config setup.

If setup was interrupted, check where it stopped with hansard init --status, then run the same hansard init command again. Setup resumes from the step that did not finish. hansard init --restart discards an unfinished setup run. It does not delete configuration, integrations, or conversations already archived.

Set up without prompts

For scripts, pass your choices as flags. --yes alone leaves recall and login startup off, so name them explicitly:

hansard init --yes --sources codex-cli,claude --watch-sources codex-cli,claude --since 30d --recall codex,claude --autostart --no-track-usage

On a new setup, --autostart also turns on plan usage tracking unless you add --no-track-usage. --no-agent-collaboration leaves agent messaging and helper agents off. Run hansard help init for every flag and hansard help import for source IDs.

Check that setup worked

hansard init --status
hansard import status
hansard status
hansard doctor
hansard watcher login status

Command	What it shows
hansard init --status	Which setup steps finished. Imports can still be running after setup finishes.
hansard import status	Progress of import runs. hansard import follow shows the current run live.
hansard status	Watcher state, archive location, conversation counts per source, and recent imports.
hansard doctor	Missing tools, source coverage, search index, login startup, and sync, with a command for each warning.
hansard watcher login status	Whether the watcher starts at login.

A working setup has an archive, finished imports for the sources you chose, recall in the agents you chose, and a running watcher. If Hansard found no history, an empty archive is expected. Restart any agent that was already open so it loads recall.

hansard doctor --deep runs slower checks across the whole archive, including importer versions and conversations whose original files are gone.

To open the app in your browser, run:

hansard web

The app opens at http://127.0.0.1:7824. On macOS and Windows, hansard app opens the desktop app instead.

Optional tools

Some sources and features use tools that may not be installed. hansard doctor reports which ones are missing. SQLite and ZIP readers are bundled on every platform. Imports do not require separate sqlite3 or unzip programs.

Tool	Used for
rg (ripgrep)	Faster hansard history search
zstd	Compressed Codex session files, when your Node.js build has no built-in Zstandard support

Update the CLI

npm install -g hansard@latest
hansard watcher restart

The CLI checks npm for a newer version once a day and prints a notice when one is available. To turn the check off, run hansard config set updates.checkOnStartup false or set HANSARD_NO_UPDATE_CHECK=1. While the watcher runs, it refreshes the recall files in your agents after each update.

Update every copy of Hansard on the computer, the desktop app and an npm installation alike. After an update, the watcher brings archived conversations up to the new release’s files in the background. To turn this off, run hansard config set archive.autoRefresh false, then run hansard rebuild --since all once. An installation that does not run the watcher runs that command too. See Refresh after updates.

Some releases change how history is imported. Their release notes name the command to run, such as hansard rebuild or hansard update. See Refresh the archive.

Uninstall

hansard uninstall
npm uninstall -g hansard

hansard uninstall stops the watcher, turns off login startup, and asks whether to delete ~/.hansard. That folder holds your settings, the archive in its default location, and any saved account profiles. To keep them, add --keep-data. The command does not remove the recall commands and skills in your agents. It lists their paths so you can delete them.

Uninstalling never changes your harnesses’ own history. To start over with a fresh setup instead, preview a reset with hansard reset --dry-run.