HypAware
View as Markdown

Generate and share reports

Reports review recorded AI work over a chosen period, from this machine's recordings or from your team's on a configured remote. Your agent examines sessions, identifies recurring patterns, and proposes changes supported by the recordings.

A report includes:

  • Overview (report.md): goals, outcomes, what deserves attention, and the ranked recommendations.
  • Comparison: changes in outcomes and token use against the preceding period of the same length.
  • Work: which projects and objectives used tokens, and what they produced.
  • Automation: usage from interactive work, unattended agents, recurring jobs, and reviews.
  • Repeated work: where retries, rework, and repeated context loading used tokens, and whether that repetition was necessary.
  • Recommendations (recommendation-<slug>.md): one page per proposed change to skills, instructions, workflows, or configuration, with evidence from the sessions that motivated it.

The report is saved as Markdown for you to read and review. You can keep it locally or publish it to HypAware Cloud to share with your organization.

Generate a report

We recommend Fable or Astra for the best report quality.

hyp report generate opens a recorded AI client that has the hypaware-report skill installed, which means Claude Code or Codex, to analyze this machine's recordings or your team's. Tell it which period to cover and what to investigate:

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

Before it starts, the skill asks for whatever your instructions leave open: the scope (this machine or the team), the period, and the focus. It suggests the last 7 days including today but waits for your answer. "Last week" means the last 7 days including today; ask for a calendar week or month to get those boundaries. Today's recordings are included and labeled partial, and the report compares the period with the preceding period of the same length.

The report skill drafts ./hypaware-report-<from>-to-<to>/, adding a numbered suffix if needed, and when the report is reviewed runs hyp report save on it, which moves the folder into ~/.hyp/reports ($HYP_HOME/reports). Every finished report is in that one place, and hyp report list shows them beside the published ones (hyp report list --local shows them alone; in JSON, only --local --json lists them, and --json alone lists published reports). The agent never writes under your home directory itself; the CLI does the move, and only a folder that would publish is admitted: report.md plus comparison.md, work.md, automation.md, repeated-work.md, usage.md, health.md, and recommendation-<slug>.md pages. The session follows the current directory's recording and sync policy, excerpts it quotes from local-only history included (PRIVACY.md). Publishing remains a separate action, using hyp report publish <name> ....

To get one recommendation instead of a full report, ask your agent for it. The hypaware-query skill answers it directly, without starting the full-report workflow:

Terminal
hyp ask "From my HypAware history, give me one recommendation about repeated test failures this week."

If you have not named a period or a focus, the agent asks for them first, suggesting the last 7 days including today. It answers in the session with a Problem: and a Fix:, followed by the supporting sessions and how to measure whether the fix worked. Ask it to save the recommendation and it writes one recommendation-<slug>.md page in the current directory; it does not save a report folder. Publish the page only if you want to share it, with hyp recommendation publish. See get one recommendation and fix it.

You can also write a Markdown report yourself with your findings, query scope, and tables. The remote renders uploaded Markdown; no local render step is needed.

Publish a report

Publishing makes the report appear in your organization's HypAware Cloud dashboard, where your team can read it.

To share the generated report with your organization, replace REPORT_NAME with the saved name printed by hyp report save (a path to a folder works too) and PERIOD with the reporting period, such as 2026-W36:

Terminal
hyp report publish REPORT_NAME --kind usage-review --period PERIOD --remote team
hyp report list --kind usage-review --limit 10 --remote team

Publishing uploads the report bundle and requires a write-capable credential. Review the report for private content first. See the report command reference for bundles, downloads, and organization-wide deletion.

To download a whole published report, open it in the dashboard and choose Export at the top of the report, then Markdown ZIP. The ZIP holds the report's Markdown pages and an export.json file with details such as the report's title, period, and recommendation ids. It does not include the recorded sessions behind the report, and links in it to the evidence behind the report may ask you to sign in to HypAware Cloud. Some older reports, published as HTML rather than Markdown, cannot be exported.

To see the recommendations your organization has not acted on yet:

Terminal
hyp recommendation list --status open

Over MCP, on your team's server at /v1/mcp, use list_recommendations.

To act on a recommendation from inside a repository, run hyp fix with the id from hyp recommendation list; it starts your agent on the change.

Terminal
hyp fix hyprec-0123456789abcdef

Over MCP, the fix_recommendation prompt does the same: the agent reads the recommendation with get_recommendation and marks it applied with set_recommendation_status, the tool for hyp recommendation mark.

If a later report finds the same problem again, a recommendation marked applied goes back to open, with the newer recommendation named as the reason.

Was this page useful?

↑↓ navigate↵ openesc close