{"id":50680351,"url":"https://github.com/hyparam/hypaware","last_synced_at":"2026-06-08T18:04:06.674Z","repository":{"id":359397639,"uuid":"1245768469","full_name":"hyparam/hypaware","owner":"hyparam","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-29T15:47:40.000Z","size":1958,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-29T17:21:22.745Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyparam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-21T14:35:44.000Z","updated_at":"2026-05-29T15:48:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyparam/hypaware","commit_stats":null,"previous_names":["hyparam/hypaware"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hyparam/hypaware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyparam%2Fhypaware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyparam%2Fhypaware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyparam%2Fhypaware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyparam%2Fhypaware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyparam","download_url":"https://codeload.github.com/hyparam/hypaware/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyparam%2Fhypaware/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34073820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T18:04:05.921Z","updated_at":"2026-06-08T18:04:06.668Z","avatar_url":"https://github.com/hyparam.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HypAware\n\nModular logs and telemetry collector. Plugin-kernel architecture.\n\nHypAware captures conversations and traffic from local AI clients (Claude\nCode, Codex), raw Anthropic / OpenAI API traffic, and OpenTelemetry\nlogs / traces / metrics into a local query cache and optional Parquet\nexports. Everything runs on the local machine — no central server is\nrequired for V1.\n\n## Quickstart\n\n```sh\nnpx hypaware\n```\n\nOn a TTY this launches the interactive walkthrough:\n\n1. Pick the **sources** to capture. Any subset of:\n   - Claude Code conversations (`claude`)\n   - Codex conversations (`codex`)\n   - Raw Anthropic API traffic (`raw-anthropic`)\n   - Raw OpenAI API traffic (`raw-openai`)\n   - OTEL logs / traces / metrics (`otel`)\n2. Pick an **export** strategy: keep the local query cache only, write\n   Parquet files under `\u003cHYP_HOME\u003e/exports`, or configure later.\n3. Pick a **retention window** (default `30` days).\n4. HypAware composes a minimal config with only the bundled plugins it\n   needs, writes it to `\u003cHYP_HOME\u003e/hypaware-config.json`, installs the\n   persistent daemon (launchd on macOS, systemd `--user` on Linux),\n   attaches the selected clients, and starts capturing.\n5. The walkthrough finishes by printing the config path, daemon status,\n   per-client attach results, and a first `hyp query` command to run.\n\nFor unattended installs (CI, scripted bootstraps, dotfiles) use the\nnon-interactive flags:\n\n```sh\nhyp init --yes \\\n  --source claude --source otel \\\n  --client claude \\\n  --export local-parquet \\\n  --retention-days 30\n```\n\nOther init flags:\n\n| Flag                       | Meaning                                                 |\n|----------------------------|---------------------------------------------------------|\n| `--yes` / `-y`             | Accept defaults; do not prompt                          |\n| `--no-daemon`              | Skip daemon install and restart                         |\n| `--dry-run`                | Render the config + planned actions, write nothing      |\n| `--client claude\\|codex`   | Attach a client (repeatable)                            |\n| `--source \u003cid\u003e`            | Add a capture source (repeatable)                       |\n| `--export \u003cchoice\u003e`        | `keep-local`, `local-parquet`, or `configure-later`     |\n| `--retention-days \u003cN\u003e`     | Override the default 30-day retention window            |\n| `--from-file \u003cconfig.json\u003e`| Skip the picker and load a known-good config            |\n| `--bin \u003cpath\u003e`             | Override the binary path the daemon installer uses      |\n\n## Where things live\n\n| Path                                           | Contents                                                 |\n|------------------------------------------------|----------------------------------------------------------|\n| `\u003cHYP_HOME\u003e/hypaware-config.json`              | Active config (rewritten by `hyp init`)                   |\n| `\u003cHYP_HOME\u003e/hypaware/`                         | Kernel state root                                         |\n| `\u003cHYP_HOME\u003e/hypaware/plugins/\u003cname\u003e/`          | Per-plugin state                                          |\n| `\u003cHYP_HOME\u003e/hypaware/cache/`                   | Local query cache (Iceberg-backed)                        |\n| `\u003cHYP_HOME\u003e/hypaware/sinks/\u003cname\u003e/outbox/`     | Failed export rows awaiting retry                         |\n| `\u003cHYP_HOME\u003e/hypaware/dev-telemetry/`           | Daemon self-telemetry (logs, traces, metrics)             |\n| `\u003cHYP_HOME\u003e/hypaware/logs/daemon.{out,err}.log`| Daemon stdout / stderr (launchd / systemd)                |\n| `\u003cHYP_HOME\u003e/exports/`                          | Local Parquet exports (when the local-fs sink is enabled) |\n\n`HYP_HOME` defaults to `~/.hyp`. Override it by exporting `HYP_HOME=...`\nbefore invoking the CLI or the daemon.\n\n## Querying captured data\n\n```sh\nhyp query sql \"select count(*) from ai_gateway_messages\"\nhyp query sql \"select count(*) from traces\"\nhyp query sql \"select count(*) from logs\"\n```\n\nUse `hyp query schema \u003cdataset\u003e` to see the columns available on each\ndataset, and `hyp query status` to inspect cache freshness per dataset.\n\n## Attaching and detaching AI clients\n\nAttach a single client (idempotent — running twice is a no-op):\n\n```sh\nhyp attach claude\nhyp attach codex\n# Equivalent flag form:\nhyp attach --client claude\nhyp attach --client codex\n```\n\nDetach (removes only HypAware-managed settings):\n\n```sh\nhyp detach claude\nhyp detach codex\n# Equivalent aliases:\nhyp detach --client claude\nhyp detach --client codex\nhyp unattach claude\nhyp unattach codex\n```\n\nBoth commands support `--dry-run` and `--json` for inspection and\nscripting. Claude writes only HypAware-related keys to\n`~/.claude/settings.json`; Codex writes a `hypaware` provider entry to\n`~/.codex/config.toml`. Unrelated keys in either file are preserved.\n\n## Daemon lifecycle\n\n```sh\nhyp daemon install      # launchd LaunchAgent (macOS) or systemd --user unit (Linux)\nhyp daemon start        # ensure the service is started\nhyp daemon status       # health snapshot\nhyp daemon restart      # bounce after a config change\nhyp daemon stop         # signal the running daemon to shut down\nhyp daemon uninstall    # remove the service file (config + recordings are kept)\n```\n\n`hyp daemon install --dry-run --json` prints the rendered plist or unit\ncontent and target paths without touching the filesystem — useful for\nverifying what `hyp init` will install.\n\n## V1 scope\n\nV1 ships with:\n\n- Bundled plugins (no external plugin install required for the default\n  flow): `@hypaware/ai-gateway`, `@hypaware/claude`, `@hypaware/codex`,\n  `@hypaware/otel`, `@hypaware/local-fs`, `@hypaware/format-parquet`,\n  `@hypaware/format-jsonl`, plus Anthropic and OpenAI upstreams.\n- Local capture for Claude Code, Codex, raw Anthropic API, raw OpenAI\n  API, and OTEL logs / traces / metrics.\n- Local query (`hyp query sql`) across captured AI gateway messages,\n  logs, traces, and metrics.\n- Local Parquet export through the `local-fs` sink and the\n  `format-parquet` encoder.\n- Claude Code attach and Codex attach (idempotent, reversible).\n- Persistent macOS / Linux user daemon (`launchd` LaunchAgent or\n  `systemd --user` unit).\n\n## Out of scope for V1\n\n- The central / enterprise sink.\n- Gascity (multi-tenant aggregation).\n- Extracting the kernel or bundled plugins into separate repos.\n- Migrating an existing Collectivus install.\n- An external first-party plugin registry. Only bundled plugins are\n  required for the default V1 path.\n\n## Troubleshooting\n\n`hyp status` is the entry point for any \"is HypAware working?\" question.\nIt prints the active config path, daemon install/run state, active\nplugins, source and sink rows, per-client attach state, retention\nwindow, cache size, and a recent-error count. Pass `--json` for the\nstable machine-readable shape that smokes and support tools rely on:\n\n```sh\nhyp status\nhyp status --json\n```\n\nWhen something is wrong, `hyp status` surfaces a `diagnostics:` section\nwith one row per finding. Each row carries a `kind` (a stable\nmachine-readable identifier) and one or more `repair:` lines you can\nrun directly. The common Phase 8 conditions:\n\n| kind                                  | meaning                                                                            | repair                                                                  |\n|---------------------------------------|------------------------------------------------------------------------------------|-------------------------------------------------------------------------|\n| `config_missing`                      | no `~/.hyp/hypaware-config.json` was found                                         | `hyp init` or `hyp init --from-file \u003cconfig.json\u003e`                       |\n| `config_invalid`                      | the loaded config failed schema / cross-plugin validation                          | `hyp init --from-file \u003cconfig.json\u003e`                                     |\n| `client_without_gateway`              | a client plugin (Claude / Codex) is enabled but `@hypaware/ai-gateway` is not      | re-run `hyp init`, then `hyp attach --client \u003cname\u003e`                     |\n| `gateway_missing_anthropic_upstream`  | `@hypaware/claude` enabled but no Anthropic upstream is registered on the gateway  | re-run `hyp init` and pick the Anthropic upstream                        |\n| `gateway_missing_openai_upstream`     | `@hypaware/codex` enabled but no OpenAI upstream is registered                     | re-run `hyp init` and pick the OpenAI upstream                           |\n| `sink_missing_encoder`                | a local-fs sink is configured but no encoder plugin is enabled                     | re-run `hyp init` and pick \"local Parquet export\"                        |\n| `client_attach_missing`               | a client plugin is enabled but its settings file shows no HypAware marker          | `hyp attach --client claude` or `hyp attach --client codex`              |\n| `daemon_binary_missing`               | the daemon installer references a binary that no longer exists on disk             | `hyp daemon install`                                                     |\n| `daemon_loaded_no_pid`                | the daemon service file is installed but launchd / systemd is not loading it       | `hyp daemon restart`                                                     |\n| `recent_errors`                       | the local telemetry directory has recent error log entries                         | inspect `~/.hyp/hypaware/dev-telemetry`, then `hyp daemon restart`       |\n\nUseful follow-on commands when a diagnostic fires:\n\n- `hyp daemon restart` — bounce the persistent daemon\n- `hyp daemon install` — re-install the launchd / systemd unit\n- `hyp attach --client claude` / `hyp attach --client codex` — wire a\n  selected client into the local gateway\n- `hyp init --from-file \u003cpath\u003e` — rebuild the config from a known-good\n  file without re-running the interactive picker\n\n## Release checklist\n\nRun before tagging a new HypAware release:\n\n```sh\nnpm test                  # if a test script is present\nnpm run lint              # if a lint script is present\nnpm run typecheck         # if a typecheck script is present\nnpm pack --dry-run        # verify the published file set\n```\n\nRe-run the V1 smoke battery and confirm every one is green:\n\n```sh\nhyp smoke package_bin_boot\nhyp smoke cli_bundled_plugins_activated\nhyp smoke daemon_foreground_start_stop\nhyp smoke daemon_install_render\nhyp smoke walkthrough_picker_to_first_query\nhyp smoke client_attach_idempotent\nhyp smoke gateway_claude_capture\nhyp smoke gateway_codex_capture\nhyp smoke otel_loopback_capture\nhyp smoke local_parquet_export\nhyp smoke status_diagnostics\n```\n\nFinally, exercise the manual gate end-to-end on at least one macOS host\nand one Linux host:\n\n```sh\nnpm pack\nnpx ./hypaware-*.tgz\nhypaware status\nhypaware daemon restart\nhypaware query sql \"select count(*) from ai_gateway_messages\"\nhypaware query sql \"select count(*) from traces\"\nhypaware query sql \"select count(*) from logs\"\nhypaware daemon uninstall\n```\n\n## Layout\n\n```\nsrc/\n  core/                 # the kernel\n    observability/      # tracer, logger, meter, attrs, span helpers\n    manifest.js\n    dep_graph.js\n    registry/           # capabilities, commands, datasets, sources, sinks\n    runtime/            # paths, activation, loader, daemon runtime\n    cache/              # intrinsic Iceberg-backed cache\n    cli/                # dispatch, walkthrough, core_commands\n    config/             # v2 schema, validator\n    daemon/             # platform installers (launchd / systemd) + lifecycle\n    plugin_install/     # resolver, fetch, lock, update_check\n    sinks/              # cron driver + encoder utility\nhypaware-core/\n  smoke/                # `hyp smoke \u003cname\u003e` flows\n  plugins-workspace/\n    ai-gateway/         # @hypaware/ai-gateway\n    otel/               # @hypaware/otel\n    local-fs/           # @hypaware/local-fs\n    format-parquet/     # @hypaware/format-parquet\n    format-jsonl/       # @hypaware/format-jsonl\n    claude/             # @hypaware/claude\n    codex/              # @hypaware/codex\n    central/            # @hypaware/central (out of scope for V1)\n    gascity/            # @hypaware/gascity (out of scope for V1)\nbin/\n  hypaware.js           # CLI entrypoint (bound to both `hypaware` and `hyp`)\n```\n\n## Project documents\n\n- [`hypaware-design.md`](./hypaware-design.md) — architecture and decisions\n- [`finish-v1.md`](./finish-v1.md) — the V1 plan of record\n- [`hypaware-implementation-plan.md`](./hypaware-implementation-plan.md) — the longer-term phased plan\n- [`docs/PLUGIN_AUTHORING.md`](./docs/PLUGIN_AUTHORING.md) — how to write a plugin (`hyp plugin new` / `hyp plugin doctor`)\n- [`collectivus-plugin-kernel-types.d.ts`](./collectivus-plugin-kernel-types.d.ts) — public plugin interfaces\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyparam%2Fhypaware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyparam%2Fhypaware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyparam%2Fhypaware/lists"}