Set up and inspect HypAware

hyp setup

hyp setup [preset] [flags]

Runs the guided setup, applies a named plugin preset, or performs an unattended configuration. It can write or replace the local configuration, install the daemon, attach clients, install client assets, and import history. --force backs up and replaces an existing configuration. Important options include repeatable --source and --client, --export, --retention-days, --from-file, --github, --no-backfill, --no-daemon, and --bin. --github enables GitHub collection (a separate opt-in that --yes never implies) without signing in; run hyp github login afterward. With --from-file, it adds GitHub to the supplied configuration and keeps its other settings. --no-backfill skips the optional one-time history imports; clients with scheduled recovery still import history. Neither flag applies to a preset.

With no arguments and no output terminal, setup prints an agent guide on stdout and exits 0 without configuring the host. It lists detected sources, recording disclosures, choices and commands, browser sign-in handoffs, and verification. An agent asks the person before selecting sources or enabling cloud sync, then runs explicit unattended flags. hyp setup --guide prints the same guide even on a terminal; use this flag alone. Cloud login from an agent shell needs hyp remote login --no-browser (print the sign-in URL) or --browser (open it); without either flag piped stdin is treated as a static token. After setup with --github, hyp github login opens the authorization page (--no-browser prints the URL and device code instead). The person completes each browser sign-in while the command waits.

--dry-run reports what would be written and writes no configuration, including with --from-file. It still refuses an existing configuration without --force, exactly where a real run would.

hyp setup --source claude --client claude --export keep-local --yes

Success returns 0. Invalid flags return 2. A refused overwrite, an unknown preset, or a --from-file configuration that cannot be read or does not validate returns 1. A failed daemon install is normally not fatal: setup returns 0 and prints a note to run hyp daemon install, so a zero exit does not prove the background service was installed. Refusing to persist a service against a non-durable CLI path, which an npx run without a global install hits, returns 1 instead.

hyp status

hyp status [--verbose] [--json]

Collects one read-only health snapshot without activating plugins. By default it prints a summary: daemon state, storage, each client's attach state and sharing policy, first-sync state, and an Attention section whose Next: lines are the commands to run. --verbose adds the inventory behind that summary: configuration, active plugins, sources, sinks, cache, recent errors, proxy trust, maintenance, recent clients, capture health, and the repair: lines under each diagnostic. Configured and live listener endpoints and endpoint drift are reported by hyp client status. Use --json for the stable machine form; --verbose does not change it.

hyp status --json

hyp ask

hyp ask ["question"]

With no argument, asks which skill would be useful to add based on your history. HypAware measures the last 30 days of recorded history, writes the evidence into <HYP_HOME>/ask (one folder, rewritten each time), and starts a recorded AI client in that folder to answer with one skill. Recorded means attached, or configured with no attach marker to write (Codex in its transcript mode); its CLI must also be on PATH. If more than one such client could be started, it asks which. A run that cannot prompt (input or output is not a terminal, or HYP_NO_TUI=1) prints the question and launches nothing, gathering no evidence; unlike the with-question path below, it takes no fallback client.

With a question, skips the gather and starts a client on that question in the current directory, asking which client should answer when more than one could. A run that cannot prompt (input or output is not a terminal, or HYP_NO_TUI=1) takes the first client of the offered set rather than failing. The offered set, on the picker too, is in ascending order of client id (claude before codex), compared character by character rather than by locale, so a newly recorded client whose id sorts earlier becomes the first. The pick is also time-bounded on a terminal: unanswered for 10 seconds, it takes that same first client and says so on stdout (No answer at the client prompt - starting the first one.). The first keypress lifts the deadline, so a pick someone is answering is never cut short. The client does not receive the bare question: it is framed with an instruction to look the answer up in the recorded sessions with hyp query first, and the typed question follows verbatim.

The client takes over the terminal. An empty cache or a declined selection succeeds. No gatherable evidence returns 1. When no recorded client can be started, hyp ask prints the same error with or without a question and returns 1; that check comes first, so it applies on an empty cache too. The error says which half is missing: a client CLI that is on PATH but not recorded is answered with the hyp client attach command to run, and no client CLI on PATH at all is answered with the binaries it looked for, since an attach would not give it anything to start. That second refusal also names any recorded client it cannot start, since neither an install nor a PATH fix would make one of those launchable either: only Claude Code and Codex declare how to be started on a question, so a recorded Cursor, OpenClaw, OpenCode, Pi or Claude Desktop is named there instead. In that second case, if a recorded client has the hypaware-query skill installed (a Claude or Codex desktop app with no CLI), hyp ask also prints the prompt to paste into the app: the typed question framed for hyp query, or for the bare form a version of the skill question that looks through the history itself, since no evidence is gathered for an app it cannot start. The prompt is the only thing written to stdout, so hyp ask | pbcopy copies it; the exit status is still 1, because nothing was started. A process-start failure returns 1 when a question was supplied; bare hyp ask currently reports that failure but still exits 0. Its exit status therefore does not prove a client started.

hyp ask "which sessions changed the authentication module"

which sessions changed the authentication module