Manage AI clients

hyp client <subcommand> [args...]

Use hyp client --help to list core and active-plugin client operations:

hyp client --help

hyp client status

hyp client status [client] [--json]

Projects the client portion of the overall status snapshot. It reports whether each client is configured, attached, attachable, recently active, and healthy. For Claude, it includes OTEL endpoint drift and recorder health.

hyp client status claude --json

hyp client attach

hyp client attach [client] [--dry-run] [--json]

Short form: hyp attach, which the guides use.

Starts recording this client. Writes only HypAware-managed client settings and installs registered skills and subagents, and turns recording back on for a client you detached. Repeating the command is a no-op. Claude Desktop has no settings to write, so attaching it only turns its recording back on. Claude Code uses its OTEL settings and requires version 2.1.193 or later. Gateway-backed clients require an active gateway configuration. OpenCode installs a HypAware-owned plugin in its shared CLI/Desktop config home and requires no gateway. --dry-run writes nothing.

hyp client attach claude --dry-run

Codex attach covers both Codex CLI and Codex Desktop because they share ~/.codex/config.toml and ~/.codex/sessions.

OpenCode attach likewise covers CLI and Desktop because they share the same XDG config home and session store.

Factory Droid attach installs managed native hooks in ~/.factory/hooks.json and requires no gateway. Restart Droid to load them. Capture reads local CLI transcripts; hosted sessions without local files are not covered.

hyp client detach

hyp client detach [client] [--dry-run] [--purge] [--json]

Short form: hyp detach, which the guides use.

Stops recording this client. Detach switches the client off in the local config ("recording": false on its plugin entry), so the daemon's scheduled transcript import and every other capture lane stop picking up its new sessions, with no daemon restart. It then replays the on-disk undo marker and removes only managed settings. Recorded history is kept; use hyp privacy purge to delete it. hyp status shows a detached client as "Not recording", with no warning. Run hyp client attach <client> to record it again. If your organization's central config requires the client, detach refuses and changes nothing. Claude telemetry detach removes the managed OTEL settings and sweeps the raw-body spool. For a legacy or other proxy attach, --purge also removes the local interception CA and its keychain trust. --dry-run writes nothing. The command doesn't ask for confirmation.

Warning: Use --purge only when you intend to remove the interception CA and its keychain trust. You need to approve keychain changes again if you later reattach through a proxy.

hyp client detach codex --dry-run

hyp client discover

hyp client discover nanoclaw [root] [--json]

Finds a supported NanoClaw v2 installation to record. With root, it checks only that path, resolved from the current directory. Without one, it checks the configured @hypaware/nanoclaw config.root, when that is absolute, and then the current directory and its ancestors, at most eight locations in all. It does not search your home or other projects.

Discovery is read-only. It checks the NanoClaw catalog and directory layout, reads no transcripts, writes no settings, and enables no capture. At least one group's Claude projects directory must exist for a root to qualify. To record a root, add @hypaware/nanoclaw with config.root set to it, validate the config, and restart the daemon (see the NanoClaw guide). A run that finds nothing still succeeds. --json prints {"client":"nanoclaw","roots":[...],"changed":false}, where roots holds each qualifying absolute root and changed is always false.

hyp client discover nanoclaw /absolute/path/to/nanoclaw --json

Client skill commands

The visible hyp client skills group contains the install command:

hyp client skills <subcommand> [args...]

hyp client skills --help

hyp client skills install

hyp client skills install [--client <name>] [--attached]

Replaces registered skill and subagent copies for one client, or for all eligible clients when you omit --client. It requires a home directory and is safe to repeat. --attached restricts installation to clients whose settings currently contain a HypAware attach marker. With no attached clients it installs nothing. Package updates use this mode so detached and never-attached clients do not get skills installed.

hyp client skills install --client codex

Claude account commands

Plugin: @hypaware/claude-account. These commands are available only when the plugin is active and configured for the intended credential mode.

hyp client claude-account <subcommand>

hyp client claude-account login

hyp client claude-account login

Starts an interactive Claude subscription OAuth flow. It opens a browser with a loopback callback and offers pasted-code fallback. It stores a refreshable credential in permission-restricted plugin state. Organization-key mode refuses because it doesn't need subscription sign-in.

hyp client claude-account login

hyp client claude-account logout

hyp client claude-account logout

Removes the locally stored subscription credential. It doesn't revoke the credential at Anthropic or remove organization-key configuration.

hyp client claude-account logout

hyp client claude-account status

hyp client claude-account status

Reports the credential mode and whether a usable credential is present. A missing, unreadable, or unresolved credential returns 1. A stored subscription credential that is past its expiry still returns 0: the command prints the expiry timestamp without comparing it, and the next resolve attempts a renewal from the stored refresh token, which fails if that refresh token has also been revoked or expired.

hyp client claude-account status

Claude Desktop commands

Plugin: @hypaware/claude-desktop.

Claude Desktop capture is supported on macOS and uses local transcripts by default. Select Claude Desktop in hyp setup; the daemon reruns the Claude history provider every five minutes. This needs no Claude account credential and makes no changes to the Desktop app.

Selecting Claude Desktop also enables Claude Code capture: the capture set below includes @hypaware/claude, the shared transcript reader, so a Desktop-only selection imports existing Claude Code CLI history from ~/.claude/projects under client_name = 'claude' and may attach Claude Code by updating ~/.claude/settings.json. Set attach.on_join: false on the @hypaware/claude entry to withhold the attach; backfill.on_join: false (below) withholds the history import.

The resulting config has this capture set:

{
  "plugins": [
    { "name": "@hypaware/ai-gateway", "config": { "upstreams": [] } },
    { "name": "@hypaware/claude" },
    { "name": "@hypaware/claude-desktop" }
  ]
}

Tune the timer in the Claude plugin config if needed:

{ "name": "@hypaware/claude", "config": {
  "backfill": { "sweep_cron": "*/10 * * * *" }
} }

The same block's window_days, if set, bounds this scheduled rerun as well as the join-time import: see "Scheduled recovery sweeps and backfill.window_days" below.

To turn the schedule off, set the same block's on_join to false. That is the opt-out from automatic history import; it withholds both the scheduled rerun and the join-time import; sweep_cron chooses a cadence and has no "never" value.

{ "name": "@hypaware/claude", "config": {
  "backfill": { "on_join": false }
} }

The subcommands below operate the older managed third-party-inference route. They are optional experiments, not prerequisites for transcript capture. They require @hypaware/claude-account; without that capability they return a repair message while the scheduled transcript imports continue normally.

hyp client claude-desktop <subcommand> [args...]

hyp client claude-desktop install

hyp client claude-desktop install [--yes] [--print-commands]

Optionally runs the attended macOS live-route setup: explains the changes, signs in if needed, writes the credential helper, backs up and clears stale dialog residue, writes the root-owned managed-preferences property list through sudo, and asks you to restart Claude Desktop. It is resumable and idempotent. --print-commands changes nothing. --yes accepts the explained local changes but doesn't bypass browser or sudo authentication.

hyp client claude-desktop install --print-commands

hyp client claude-desktop status

hyp client claude-desktop status

Reports the resolved endpoint, credential mode, helper path, models, and bundle ID. A missing helper returns 1, and so does a generated helper whose baked interpreter or CLI path has rotted away, which prints STALE and names the re-run. This command doesn't verify the installed property list.

hyp client claude-desktop status

hyp client claude-desktop verify

hyp client claude-desktop verify

Checks that the managed property list is present and current, that the credential wrapper it names is present and still runnable, and that stale dialog residue is cleared. Those automatic checks determine the exit code. It also prints a manual in-app capture check, which doesn't affect the exit code.

hyp client claude-desktop verify

hyp client claude-desktop profile

hyp client claude-desktop profile [--plist] [--out <path>]

Renders a secret-free managed third-party-inference profile as JSON, or as a managed-preferences property-list dictionary with --plist. --out writes the result to a file. Install the helper first.

hyp client claude-desktop profile --plist --out ./claude-desktop.plist

hyp client claude-desktop install-helper

hyp client claude-desktop install-helper [--path <path>]

Writes the executable, no-argument credential wrapper that the Desktop profile references. The default location is in plugin state and outside protected desktop directories.

hyp client claude-desktop install-helper