# Manage AI clients Canonical: https://hypaware.ai/docs/cli-reference/manage-ai-clients ```text hyp client [args...] ``` Use `hyp client --help` to list core and active-plugin client operations: ```sh hyp client --help ``` ## `hyp client status` ```text 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. ```sh hyp client status claude --json ``` ## `hyp client attach` ```text 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. ```sh 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](https://hypaware.ai/docs/integrations/droid/index.md) 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` ```text 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`](https://hypaware.ai/docs/cli-reference/index.md#hyp-privacy-purge) to delete it. `hyp status` shows a detached client as "Not recording", with no warning. Run `hyp client attach ` 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. ```sh hyp client detach codex --dry-run ``` ## `hyp client discover` ```text 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](https://hypaware.ai/docs/integrations/nanoclaw/index.md)). 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`. ```sh hyp client discover nanoclaw /absolute/path/to/nanoclaw --json ``` ## Client skill commands The visible `hyp client skills` group contains the install command: ```text hyp client skills [args...] ``` ```sh hyp client skills --help ``` ### `hyp client skills install` ```text hyp client skills install [--client ] [--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. ```sh 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. ```text hyp client claude-account ``` ### `hyp client claude-account login` ```text 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. ```sh hyp client claude-account login ``` ### `hyp client claude-account logout` ```text hyp client claude-account logout ``` Removes the locally stored subscription credential. It doesn't revoke the credential at Anthropic or remove organization-key configuration. ```sh hyp client claude-account logout ``` ### `hyp client claude-account status` ```text 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. ```sh 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: ```json { "plugins": [ { "name": "@hypaware/ai-gateway", "config": { "upstreams": [] } }, { "name": "@hypaware/claude" }, { "name": "@hypaware/claude-desktop" } ] } ``` Tune the timer in the Claude plugin config if needed: ```json { "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. ```json { "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. ```text hyp client claude-desktop [args...] ``` ### `hyp client claude-desktop install` ```text 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. ```sh hyp client claude-desktop install --print-commands ``` ### `hyp client claude-desktop status` ```text 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. ```sh hyp client claude-desktop status ``` ### `hyp client claude-desktop verify` ```text 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. ```sh hyp client claude-desktop verify ``` ### `hyp client claude-desktop profile` ```text hyp client claude-desktop profile [--plist] [--out ] ``` 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. ```sh hyp client claude-desktop profile --plist --out ./claude-desktop.plist ``` ### `hyp client claude-desktop install-helper` ```text hyp client claude-desktop install-helper [--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. ```sh hyp client claude-desktop install-helper ```