Install and maintain HypAware

Install HypAware, check its background service, and keep the installation up to date.

For the syntax and behavior of every command, see the HypAware CLI command reference.

Requirements

• Node.js 22.12 or later.
• macOS with launchd, Linux with a systemd user service, or Windows with Task Scheduler, for the persistent background service. A container or CI host without one can run hyp daemon run in the foreground instead; see CI and headless deployment.
• An interactive terminal for the guided setup.

Install HypAware

Install the CLI globally, then run the guided setup:

npm i -g hypaware
hyp setup

Install HypAware using npm i -g hypaware, then run hyp setup --guide and follow its instructions.

Select Sync to the cloud to store your recordings on HypAware Cloud or choose Local only to keep recordings on your host. To change this later, see connect a host.

Setup then asks which AI clients to record, installs the background service, connects the clients you selected, and imports their supported session history.

If a valid configuration already exists, hyp setup lets you reconfigure the setup.

hyp setup runs the same way on Windows as on macOS and Linux. On any of them you can instead install the service with hyp daemon install and connect each client with hyp client attach <client>.

For an unattended local installation, specify each choice:

hyp setup --yes \
    --source claude \
    --source otel \
    --client claude \
    --export keep-local \
    --retention-days 90

--dry-run previews an unattended setup: it reports what would be written and writes no configuration. The flag always runs setup non-interactively, so name the choices to preview with --yes, --source, --client, or --from-file; on its own it stops with "no sources selected". The guided setup has no preview. If a configuration already exists, add --force to replace it. HypAware backs up the existing configuration before replacement.

Check the installation

hyp status

Run hyp status and tell me whether HypAware is installed and recording correctly, and what to fix if not.

HypAware · Needs attention

  Daemon     Running
  Storage    37 MB · 90-day retention
  Sharing    Organization sync configured
  new folders:     sync without asking (`hyp privacy folders ask` to be asked instead)

  Clients                 Status                           Data
  claude                  Telemetry may be interrupted     Sync
  codex                   Recording                        Sync

  Sync = organization sharing policy, not delivery confirmation.

Attention
  ! claude: transcripts active 1m ago; last telemetry 21m ago.
    Next: hyp daemon restart

More details: hyp status --verbose

Status reports the background service, clients, storage, and anything that needs attention, with guidance to help resolve problems. For capture checks, see clients and history; for failures, see troubleshooting.

Manage the background service

The daemon keeps capture and scheduled sync running after you close the terminal. Setup installs it as a per-user service. On macOS, its LaunchAgent runs while you are logged in. On Linux, its systemd user service requires user-session support; see headless deployment for hosts that must keep running after logout.

On Windows, it is a per-user Scheduled Task, \hypaware\<SID>, where <SID> is your Windows security identifier. It runs as you and needs no administrator rights. It stops when you sign out and starts again when you next sign in. If the daemon crashes, Windows relaunches it within about a minute; a clean exit, such as the one hyp daemon stop asks for, leaves it stopped. No console window opens: the task runs the daemon through a generated launcher, .hyp\hypaware\daemon-launcher.vbs in your user profile (next to the logs directory), using wscript. Install writes the launcher, and hyp daemon uninstall deletes it along with the task.

On Windows, hyp daemon stop first asks the daemon to exit cleanly. If it is still running after 10 seconds, stop force-ends the task and the daemon it launched, and says so. hyp daemon restart stops the daemon the same graceful way and then runs the task again; it force-ends the task only when the stop request does not land.

hyp daemon status
hyp daemon restart

Use the daemon reference for start, stop, install, and foreground operation.

Reconfigure an installation

For an ordinary interactive reconfiguration, run:

hyp setup

Select Reconfigure in the menu. HypAware preserves a centrally managed configuration layer and changes only the choices this host owns.

For unattended replacements and configuration files, see repeatable configuration.

Update HypAware

HypAware updates automatically by default when installed globally and running as a background service. To update now:

hyp update

The command installs the latest release and restarts the background service.

npm install -g hypaware@NEXT_MAJOR_VERSION
hyp version
hyp config validate
hyp daemon install
hyp status

Replace NEXT_MAJOR_VERSION with the version you reviewed. Set top-level "auto_update": false and restart the daemon first, or the next automatic check moves off the version you pinned; centrally managed policy may own that choice. Do not assume --yes accepts a breaking migration, because no such acceptance contract exists. If validation fails, stop and restore the saved copy.

Reinstall or recover the current version

If the CLI binary or service definition is missing but your state is intact, reinstall the package and service:

npm install -g hypaware
hyp daemon install
hyp status

To restore a known-good configuration, follow repeatable configuration.

Use hyp attach <client> for any configured client that status reports as detached, replacing <client> with its name, such as claude or codex.

Uninstall

hyp leave                  # if this host is enrolled in Cloud
hyp daemon uninstall
npm uninstall -g hypaware

Daemon uninstall restores managed client settings and retains local configuration and recordings. To delete recorded data, see privacy. Copies already synced to Cloud or exported to files are not removed by uninstall.