# Quickstart

Canonical: https://hypaware.ai/quickstart (HTML version)

From nothing to your first findings on one host. A host is any machine the collector runs on: a laptop, a build box, a remote agent's box. Then connect it to your team.

Most steps work from your agent too. Switch a box to agent, copy the prompt, and paste it into Claude Code, Codex, or whichever agent you use.

## Before you start

You need Node.js 22.12 or newer, and macOS or Linux. HypAware runs as a small daemon that stays up between sessions: launchd on macOS, a user-level systemd service on Linux. It records the AI coding tools you already use: Claude Code, Codex, Cursor, OpenCode, Pi, OpenClaw, Hermes, etc.

## 1. Install

```sh
npm i -g hypaware
hyp setup
```

Setup walks you through it: pick the tools to record, install the daemon, and attach the tools you picked. When it finishes it shows you what it has already found on the host.

## 2. Check it is capturing

```sh
hyp status
```

This is the answer to "is HypAware working." It shows the daemon, what is being recorded, which tools are attached, the retention window, and anything that needs attention. Add `--json` for machine-readable output.

## 3. Look at what you already have

```sh
hyp query overview
```

Your history was already on the host. This summarizes it: sessions, tools, models, and tokens over the last 30 days.

## 4. Ask it a question

```sh
hyp ask "From my HypAware history, which repo used the most tokens this month, and which model?"
```

To find out what repos are consuming the most tokens this month.

```sh
hyp ask "From my HypAware history, where did my agents go off the rails recently?"
```

To see where agents got stuck.

```sh
hyp ask "From my HypAware history, which tools failed most often this week?"
```

To find where the agents are having repeated tool failures.

## 5. Generate a report

A report is your agent reading your recent sessions and writing up what it found: usage, the work itself, where sessions broke down, and specific changes to make, with the sessions behind each one. It runs in Claude Code or Codex, so one of them needs to be recorded. Tell it the period and what to look into:

```sh
hyp report generate "Cover last week and focus on repeated debugging work"
```

To see where your agents kept fixing the same problems.

```sh
hyp report generate "Cover the last two weeks and focus on tool failures and retries"
```

To find the tools and commands that keep failing, and what to change.

```sh
hyp report generate "Give me one recommendation about repeated test failures"
```

To get a single recommendation instead of a full report.

With no instructions, a report covers the previous calendar month. Finished reports are saved on this host, and `hyp report list` shows them. To share one with your team, connect first (step 7), then publish it with its saved name and the period it covers, such as `2026-W41`:

```sh
hyp report publish REPORT_NAME --kind usage-review --period PERIOD --remote team
```

Published reports appear in your organization's HypAware Cloud dashboard, where your team can read them. Read the report for anything private before you publish it.

## 6. Fix a recommendation

In the repository a recommendation applies to, run `hyp report fix`. It lists your published reports and their recommendations, and starts your agent on the one you pick. To fix a single recommendation, publish its page first with `hyp report recommend`.

```sh
hyp report fix
```

To go straight to one recommendation, pass its ID. `hyp report list` prints the ID under each report:

```sh
hyp report fix hyprec-0123456789abcdef
```

When the change lands, your agent marks the recommendation applied, with the pull request link.

## 7. Connect to your team

```sh
hyp remote login
```

Works whether you have an account or not. It opens a browser sign-in, enrolls this host with your organization, and starts forwarding what it records. From then on you can query across every connected host, not only your own:

```sh
hyp ask "From our HypAware team history, which of our sessions this week reached a pull request?"
```

To find out where your software factory is shipping.

One person can sign in and sync on their own. To add teammates to your organization, contact us at [hypaware.ai/contact](https://hypaware.ai/contact).

## 8. Control what is recorded

Mark any folder as ignore (never recorded), local-only (recorded, never synced), or sync, with a `.hypignore` file in the repo or with the `hyp privacy` commands. To be asked before each new folder is synced:

```sh
hyp privacy folders ask
```

To keep one conversation out of the record, `hyp session ignore`. To delete local recordings, `hyp privacy purge`. To stop syncing this host, `hyp leave`.

## 9. Add or remove a tool

```sh
hyp attach claude
```

Attaching is idempotent; run it again and nothing changes.

```sh
hyp detach claude
```

Removes only the settings HypAware added. Then `hyp status` to confirm.

## Where to go next

The full reference, every command and every option, is in the docs. If something in this guide didn't work the way it says, talk to an engineer; that is exactly the kind of thing we want to hear.