Installation

The standalone macOS app includes its runtime and does not require Node.js or npm. CLI installation requires Node.js 20 or newer and supplies the CLI and local browser viewer.

Install with your agent

Copy this prompt into a coding agent with access to the machine's terminal:

Install and fully set up Hansard on this machine. Check for Node.js 20 or newer,
then install the published CLI with npm install -g hansard. Read the installed
hansard/skills/setup/SKILL.md (find the package directory with npm root -g).
Run the bounded setup preview and check disk space first. Use local storage,
import the last 30 days from detected local sources, install recall for supported
agents already present, enable same-project agent collaboration, and start the
watcher with login startup. Open the viewer and verify setup, imports, recall,
and watcher health. Preserve any existing archive and preferences. Leave remote
sync, sharing, telemetry, CLI usage tracking, and agent access to memories off
unless already configured. Ask only for missing choices or a blocking issue;
complete the authorized steps and report anything still pending.

The setup guide ships with the npm package. This prompt authorizes local setup, a 30-day import, recall integration, and background archiving. Change those choices in the prompt before sending it when needed.

Install in a terminal

Global

Install globally when Hansard should be available to coding agents and from any working directory:

npm install -g hansard
hansard init
hansard doctor
hansard status
hansard app

Project local

Install inside one project when a pinned local dependency is preferable:

npm install hansard
npx hansard init

Run with npx

Run the published package without retaining a project dependency:

npx hansard init

If the native app is unavailable, run hansard web to use the browser viewer.

Installing the package does not complete setup. Hansard does not run its own install-time lifecycle scripts. hansard init configures sources, queues history imports, installs selected recall integrations, and enables selected background services. In the wizard, select recall and login startup to use history from agents and keep archiving new conversations.

For unattended installation, hansard init --yes still requires --recall and --autostart to enable recall and login startup. Use the agent prompt above for a complete guided installation with explicit choices and verification.

Verify setup

Check both setup and import state:

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

Setup can finish while historical imports continue in the background. Use hansard import follow to watch progress. A ready installation has a configured archive, completed imports for the selected sources, the requested recall integrations, and the requested watcher and login-startup states. If no local history is detected, the archive can legitimately be empty. Restart or reload an already-open agent to load its new recall integration.

For interrupted setup, inspect hansard init --status and rerun the original init command to resume. For a configured installation, hansard config setup revisits preferences without starting another import.

Optional system tools

Different importers use different local utilities:

Tool	Used for
sqlite3	Codex, Cursor, and Devin SQLite source stores
rg	Faster history and recall searches
unzip	ZIP exports from web products
zstd or unzstd	Compressed Codex session files

Run the health check after installation:

hansard doctor

The command reports missing tools, a bounded inventory of configured source history, search-index state, watcher autostart registration, and whether remote sync is configured. Run hansard doctor --deep for archive-wide parser-version, unavailable-source, and import-health checks. Use hansard status for the live watcher state.

Native macOS app

The macOS installer provides the standalone app. The npm package does not contain the native bundle. On macOS, hansard app opens an installed app or installs it from the published desktop release when available. If no desktop release has been published, the command reports that explicitly; hansard web opens the local browser viewer.

Use hansard app install to install or update the native app. For a downloaded installer, use hansard app install --from /path/to/Hansard.dmg. The hansard app --no-fallback check opens only an existing native app and never downloads one.

Preview initialization

Run hansard init --dry-run to run bounded read-only source inventory and storage preflight, then inspect every setup stage and possible write before creating configuration or importing history.

Interactive setup explains the canonical local archive first. Its bounded source inventory may begin in an isolated read-only child while local setup questions are open; it reads filesystem metadata under fixed budgets, does not parse transcripts, and cannot write configuration or start an import. Use the arrow keys and Space to choose initial-backfill and live-watcher sources, then press Enter to confirm. R2, S3, and custom remote sync are optional and are offered only after the local setup is ready; hansard sync configure can add or change a remote later.

On rerun, setup offers to keep, edit, or reset the saved backfill, watcher, and deferred-source choices. Edit reopens both checklists with the saved state; every path ends at one combined review before those choices are written.

Storage preflight reports local source bytes separately from the projected archive range. Hansard copies provider history; it does not download local backfill data. The projection accounts for preserved raw records and the normalized transcript, event, Markdown, viewer, and index layers, while keeping a recovery reserve free. Lower-bound scans and artifact-capture exclusions stay explicit rather than being presented as exact estimates.