HypAware
Get a demo
View as Markdown

Explore and query recordings

After setup, use your AI agent to explore your recordings. You can start a question with hyp ask or ask the client you already have open to use HypAware. Search and SQL commands are also available below. To generate or share a report, see reports.

Queries use this host's recordings by default. To search recordings in HypAware Cloud, including other hosts and your team, tell your agent to use --remote on its query commands. This uses your default remote target; --remote <target> selects another. See remote access to configure a target and sign in.

Explore recordings with your agent

Choose either option below.

Ask your client directly

In an existing client session, ask it to use HypAware:

Use HypAware to find the session where we fixed the authentication bug.

You can also ask it to search remote logs:

Use HypAware to search my remote logs for the session where we fixed the authentication bug.

HypAware's skills are installed automatically during setup and attach for supported clients. They let your agent search recorded sessions and query the logs. If the skills are missing, see client skills.

Use hyp ask

From your terminal, ask a question about your recordings:

Terminal
hyp ask "Use HypAware to search my remote logs for sessions about connection refused this week."

hyp ask opens a recorded AI client (Claude Code or Codex) and asks it to look up the answer in HypAware. If both are configured and available, you can choose which one to use.

See what is available

Terminal
hyp cache status
hyp query overview
hyp query schema ai_gateway_messages
Output
What HypAware has recorded
2026-09-01 to 2026-09-06 (5 active days, 1,565 rows)
────────────────────────────────────────
Input is prompt sent fresh; cached is prompt served from (or written to) the cache.
Output is what the model generated. Input + cached is the whole prompt.
Share bars split ▒ input from █ output; cache is excluded.

Which providers and models you use, by volume

  provider   model              input      cached   output  share
  anthropic  claude-opus-5-5   25,252  64,078,478  263,270  ▒▒████████████████
  openai     gpt-6.1-sol       61,926     612,992    1,284  ▒▒▒█
  anthropic  claude-haiku-5-5  20,423           0    1,273  █

Over MCP, read the same datasets with query_sql.

Cache status lists local datasets and freshness. The overview summarizes models, tokens, repositories, and tools over the period printed in its heading. Its default window adapts to the amount of data; use --days 7 for a chosen window, --json for structured output, or --sql to inspect its queries.

ai_gateway_messages contains message parts: one message can contribute several text, tool-call, or tool-result rows. A row count is not a count of sessions, messages, or API requests. Other datasets depend on enabled sources; inspect their schema before writing SQL.

Find a conversation

The bundled @hypaware/grep plugin searches recorded messages. Standard capture setups enable it; an explicit enabled: false entry keeps it disabled. An existing configuration gains it automatically on startup. When the migration can save the change it backs the config up first, leaving a timestamped .bak- copy beside hypaware-config.json; otherwise search still works for that process, and a read-only config logs a warning that the change could not be saved.

Terminal
hyp query grep "connection refused" --limit 20
hyp query grep "daemon" --from 2026-09-01 --to 2026-09-07 --format json
Output
date        session_id                            column        message_id                            part_id                                 snippet
----------  ------------------------------------  ------------  ------------------------------------  --------------------------------------  --------------------------------------------------------------------------------
2026-09-07  5bb16021-a2a1-433d-91a0-6afc69732b6d  content_text  99651a15-be1f-428a-85ff-56a0183a7a4c  99651a15-be1f-428a-85ff-56a0183a7a4c#0  ...daemon log: connect ECONNREFUSED 127.0.0.1:4318 (connection refused)
2026-09-05  1e56b730-1ce4-46f8-b7fc-7961a4087ada  content_text  39cf0bc2-2d8b-4c25-a752-54c9cbbd497e  39cf0bc2-2d8b-4c25-a752-54c9cbbd497e#0  ...the gateway is down, so every request fails with connection refused until the
2026-09-05  1e56b730-1ce4-46f8-b7fc-7961a4087ada  content_text  559ea13b-be2e-464c-ae03-aabcd78838ae  559ea13b-be2e-464c-ae03-aabcd78838ae#0  ...curl: (7) Failed to connect to localhost port 4318: Connection refused\n

Over MCP, use grep_search.

Replace the dates with the period you need. Search is a case-insensitive substring match unless you pass --regex. Each hit identifies a session, message, and part, with newest hits first. One part can match several columns.

Search covers content_text, tool_name, session_id, conversation_id, agent_id, model, cwd, git_branch, and git_remote. It does not search system prompts or tool arguments. Inspect those with SQL when needed.

Take a session_id from a hit and read its conversation:

Terminal
hyp query sql "select message_index, part_index, role, part_type, content_text, tool_name
  from ai_gateway_messages
  where session_id = 'SESSION_ID'
  order by message_index, part_index
  limit 100" --format json

A session_id filter alone can read every day of the cache, because the cache is partitioned by date. If you know the days the session ran, add and date >= 'FIRST_DAY' and date <= 'LAST_DAY' so only those days are read. Cover every day: a session can cross midnight, and rows outside the range are silently left out.

To inspect that session's tool calls:

Terminal
hyp query sql "select message_index, tool_name, tool_args
  from ai_gateway_messages
  where session_id = 'SESSION_ID' and part_type = 'tool_call'
  order by message_index
  limit 50" --format json

Over MCP, every SQL query in this section runs with query_sql.

Summarize a known period

Use explicit date bounds so the result has a clear scope. This counts sessions and parts per client per day; a session spanning days can count on each day.

Terminal
hyp query sql "select date, client_name,
    count(distinct session_id) as sessions, count(*) as parts
  from ai_gateway_messages
  where date >= '2026-09-01' and date < '2026-09-08'
  group by date, client_name
  order by date desc, client_name" --format markdown

Over MCP, every SQL query in this section runs with query_sql.

For token summaries, start with hyp query overview --days 7 --sql and its existing usage extraction. Token usage is stored in structured attributes; do not assume every message part has usage or represents another request.

Find the turns a person typed

A role = 'user' text row is not always something a person typed. Skill expansions, system reminders, tool output echoes, task notifications, messages from other agents, interrupts, and compaction summaries are recorded as user text too. Since HypAware 1.48.0, Claude Code and Codex rows record who submitted the turn:

  • Claude Code and Claude Desktop: JSON_EXTRACT_STRING(attributes, '$.claude.origin.kind') = 'human'. attributes.claude.prompt_source adds how the turn was submitted: typed, queued, suggestion_accepted, sdk, or system. A 'human' turn can be any of the first three; add JSON_EXTRACT_STRING(attributes, '$.claude.prompt_source') = 'typed' to keep only turns typed at the prompt. A headless claude -p turn has prompt_source = 'sdk' and no origin.
  • Codex: JSON_EXTRACT_STRING(attributes, '$.codex.content_item_kinds') contains "user.text".

This counts typed turns per client per day:

Terminal
hyp query sql "select date, client_name, count(*) as typed_turns
  from ai_gateway_messages
  where date >= '2026-11-02' and date < '2026-11-09'
    and role = 'user' and part_type = 'text'
    and (JSON_EXTRACT_STRING(attributes, '$.claude.origin.kind') = 'human'
      or JSON_EXTRACT_STRING(attributes, '$.codex.content_item_kinds') like '%\"user.text\"%')
  group by date, client_name
  order by date desc, client_name" --format markdown

Not every other row is unlabeled. Claude Code gives task notifications, peer messages, and coordinator turns their own origin.kind (task-notification, peer, coordinator), and leaves tool results, subagent prompts, skill expansions, interrupts, and compaction summaries with no origin at all. Codex labels injected blocks with other kinds, such as agents_md.instructions and environments.environment_context. Filter on = 'human' and "user.text"; a row with some label is not a typed turn.

The labels need HypAware 1.48.0 or later on the machine that recorded the row, Claude Code 2.1.241 or later, and Codex 0.151.0 or later. Rows recorded before that never get a label, and maintenance does not add one later, so a label-only count is low for every earlier day and every machine that has not upgraded. Check coverage first:

Terminal
hyp query sql "select date, client_name, count(*) as user_rows,
    sum(case when JSON_EXTRACT_STRING(attributes, '$.claude.origin.kind') = 'human'
      or JSON_EXTRACT_STRING(attributes, '$.codex.content_item_kinds') like '%\"user.text\"%'
      then 1 else 0 end) as typed_turns
  from ai_gateway_messages
  where date >= '2026-10-01' and role = 'user' and part_type = 'text'
  group by date, client_name
  order by date desc, client_name" --format markdown

A day with user rows but no typed turns most likely predates the label. On a remote target, add gateway_id to the grouping to find the machines that have not upgraded.

For those days, estimate Claude Code typed turns from the text. This keeps main-thread rows and drops the common injected prefixes:

Terminal
hyp query sql "select date, count(*) as estimated_typed_turns
  from ai_gateway_messages
  where date >= '2026-10-01' and date < '2026-11-01'
    and client_name = 'claude' and role = 'user' and part_type = 'text'
    and coalesce(is_sidechain, false) = false
    and (agent_id is null or agent_id = '')
    and (user_type is null or user_type in ('external', 'user'))
    and (entrypoint is null or entrypoint <> 'sdk-cli')
    and content_text not like '<%'
    and content_text not like '[%'
    and content_text not like 'Base directory for this skill%'
    and content_text not like 'Tool loaded.%'
    and content_text not like 'Skill /%'
    and content_text not like 'Re-invocation of %'
    and content_text not like 'Another Claude session sent%'
    and content_text not like 'The user sent a new message while%'
    and content_text not like 'This session is being continued%'
    and content_text not like 'From my HypAware history%'
    and content_text not like 'Message Type:%'
  group by date
  order by date desc" --format markdown

Report these counts as estimates. The filter still counts smoke prompts and pasted documents, and it drops a typed message that starts with a bracket. Codex has no reliable text rule before the label. Count its main-thread user text rows (client_name = 'codex' and role = 'user' and part_type = 'text' and coalesce(is_sidechain, false) = false) and say that they include injected blocks.

Over MCP, every SQL query in this section runs with query_sql.

Save complete results

Terminal output truncates long cells and limits the displayed byte count. Notices on standard error explain omitted data. Write to a file when you need complete results from your query:

Terminal
hyp query sql "select message_index, part_index, role, content_text
  from ai_gateway_messages where session_id = 'SESSION_ID'
  order by message_index, part_index" --format jsonl --output ./session.jsonl

Over MCP, run the same SQL with query_sql; the agent saves the rows itself, since --output is a local option.

--output avoids terminal display truncation; it does not remove a SQL LIMIT. Available formats include table, json, jsonl, and markdown. Keep stderr separate from JSON output so freshness and privacy notices remain visible.

Query a remote target

Terminal
hyp remote list
hyp query grep "connection refused" --remote team --limit 20
hyp query sql "select date, count(distinct session_id) as sessions
  from ai_gateway_messages
  where date >= '2026-09-01' and date < '2026-09-08'
  group by date order by date" --remote team --format json

Over MCP, use grep_search and query_sql on your team's server, either on /v1/mcp or through hyp mcp serve --remote.

Replace team with a configured target. A bare --remote uses the default. For target configuration and query-only sign-in, see remote access.

hyp cache status and hyp query overview describe local state. They are not a remote inventory. A remote can have different datasets, retention, and permissions; query it directly to establish what is available. To see a remote dataset's columns, add --remote to hyp query schema, which resolves the target the same way hyp query sql does. The remote enforces visibility and rejects --include-local-only.

Follow relationships in the activity graph

When @hypaware/context-graph is active, project local recordings before walking relationships:

Terminal
hyp graph project
hyp query graph neighbors src/app.js --type File --direction in --depth 2 --limit 25

Over MCP, use graph_neighbors.

Replace the example file with one from your recorded work. A seed can be a node ID, natural key, or label. An ambiguous seed needs a type or exact ID. A file can have both a repository-relative identity and an absolute-path identity.

Use the graph for questions such as which sessions touched a file or show skill evidence for a skill. Skill evidence says how the session reached the skill (an invocation requested, its instructions supplied, or its file read or searched), not that the skill ran or succeeded. A Session node's natural key is the session_id to use in the SQL examples above. The node and edge datasets are also queryable with SQL. Remote graph traversal uses --remote; projecting the local graph does not refresh the remote's graph.

Explore the team's history

The shipped Claude and Codex query skills teach agents to search the team server's graph for specific filenames, follow those files to promising sessions, search a small batch of sessions, and verify the original conversation. If the first batch misses, the agent refines the file leads before expanding its search. The server's session index accelerates eligible session-scoped reads.

This uses existing remote tools:

Terminal
hyp query sql "SELECT node_id, natural_key, label FROM node WHERE node_type = 'File' AND LOWER(natural_key) LIKE '%<feature>%' ORDER BY natural_key LIMIT 40" --remote team --format json
hyp query graph neighbors <file-node-id> --type File --direction in --edge-type touched --depth 1 --limit 50 --remote team --json
hyp query grep "<term>" --session-id <session-id> --remote team --format json

Over MCP, the three steps are query_sql, graph_neighbors and grep_search on your team's server.

Replace placeholders with terms and IDs from the question and results. A Session node's natural_key is the message dataset's session_id. Read the surrounding messages with session-scoped remote SQL, or use the remote session_evidence MCP tool when advertised. File names and graph links are leads, not proof of what was decided. Check incomplete results and later relevant sessions before concluding whether a decision still stands.

Team retrieval needs no replicated graph or additional client plugin. The server maintains the graph. This host's own capture graph remains available for local activity questions. If remote graph data is unavailable, use remote message searches and disclose that coverage limit.

Connect an MCP client

See Connect an MCP client for local and remote setup, with a config block for each client.

Vector search and graph enrichment

With @hypaware/vector-search enabled, use hyp vector status to inspect indexes and hyp query vector search for similarity search. See the vector search reference for query syntax and index selection.

The optional graph-enrichment plugin adds further relationships to the activity graph. Use hyp enrichment status to inspect its state, then consult the enrichment reference for proposal, curation, and backfill operations.

Was this page useful?

↑↓ navigate↵ openesc close

Talk to an engineer

Talk to Sales