### Install Hypa

Source: https://github.com/hypabolic/hypa/blob/main/python/README.md

Install the Hypa package using pip. This is the initial setup step.

```bash
pip install hypa
```

--------------------------------

### Generic Compression Wrapper Examples

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Examples of custom tools that are wrapped by Hypa for compression and optimized execution.

```text
custom-tool check -> hypa -c "custom-tool check"
```

--------------------------------

### First-Class Command Module Examples

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Examples of commands that are rewritten to their Hypa-specific equivalents for optimized execution.

```text
git status        -> hypa git status
dotnet test       -> hypa dotnet test
kubectl get pods  -> hypa kubectl get pods
```

--------------------------------

### Hypa Command Reference Examples

Source: https://github.com/hypabolic/hypa/blob/main/src/Hypa.Infrastructure/Skills/Resources/SKILL.md

Provides examples for using Hypa with Git, Dotnet, Docker, and Kubectl commands, along with the generic command wrapper.

```bash
hypa git status
```

```bash
hypa git diff
```

```bash
hypa git log --oneline
```

```bash
hypa dotnet build
```

```bash
hypa dotnet test
```

```bash
hypa dotnet restore
```

```bash
hypa docker ps
```

```bash
hypa docker logs <container>
```

```bash
hypa docker build .
```

```bash
hypa kubectl get pods
```

```bash
hypa kubectl describe pod <name>
```

```bash
hypa kubectl logs <pod>
```

```bash
hypa -c "any command"
```

--------------------------------

### Lazy Tool Exposure Examples

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Examples demonstrating how optional advanced tools can be exposed on demand using specific actions.

```text
hypa_diagnostics action=tools
hypa_context action=discover
```

--------------------------------

### Host Adapter Behavior for Mutable Input

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Example of a suggestion for hosts without mutable input, guiding the user to use Hypa wrappers for compact output.

```text
Use `hypa git status` instead for compact output.
```

--------------------------------

### Starting and Configuring MCP Server

Source: https://github.com/hypabolic/hypa/blob/main/src/Hypa.Infrastructure/Skills/Resources/SKILL.md

Start the MCP stdio server using `hypa serve`. Options include running in read-only mode to disable mutating tools or exposing only specific tools by name.

```bash
hypa serve                              # start MCP stdio server
hypa serve --read-only                  # disable mutating tools (index, shell writes)
hypa serve --tool hypa_shell            # expose only specific tools
```

--------------------------------

### Install Hypa on Linux/macOS

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Installs Hypa by downloading the latest release script and executing it. This is the recommended method for Linux and macOS users.

```bash
curl -fsSL https://hypabolic.github.io/Hypa/install.sh | sh
```

--------------------------------

### Install Hypa Globally

Source: https://github.com/hypabolic/hypa/blob/main/npm/hypa/README.md

Installs the Hypa command-line tool globally on your system.

```bash
npm install -g @hypabolic/hypa
```

--------------------------------

### Example Rewrite Rules

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Illustrative examples of rewrite rules for 'git status' and 'dotnet test', specifying patterns, targets, and estimated savings.

```text
id = git-status
pattern = ^git\s+status(\s|$)
target = hypa git
kind = FirstClassCommand
estimated = 70

id = dotnet-test
pattern = ^dotnet\s+test(\s|$)
target = hypa dotnet test
kind = FirstClassCommand
estimated = 85
```

--------------------------------

### Install pi-hypa Extension

Source: https://github.com/hypabolic/hypa/blob/main/packages/pi-hypa/README.md

Install the pi-hypa extension package using the 'pi' command. This can be done by specifying the local extension path or by installing a released version from npm.

```bash
pi -e ./packages/pi-hypa/extensions/index.ts
```

```bash
pi install ./packages/pi-hypa
```

```bash
pi install npm:@hypabolic/pi-hypa
```

--------------------------------

### Install Hypa Globally

Source: https://github.com/hypabolic/hypa/blob/main/npm/hypa-platform/README.md

Install the main Hypa package globally. This will also install the platform-specific native binary as an optional dependency.

```bash
npm install -g @hypabolic/hypa

```

--------------------------------

### Active Run Manifest Protocol Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/feature-parity-roadmap.md

An example JSON structure for the active run manifest file (`~/.atomic/active-run.json`). This file signals the start of a job run to the Hypa daemon.

```json
// ~/.atomic/active-run.json
{
  "schema_version": 1,
  "run_id": "<uuid>",
  "job_id": "<uuid>",
  "workspace_id": "<uuid>",
  "started_at": "<rfc3339>",
  "agent_kind": "claude",
  "project_root": "/path/to/project"
}
```

--------------------------------

### Command Rewrite Examples

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0005-command-rewrite-registry.md

Illustrates various shell commands and their corresponding rewrite decisions, including target types.

```text
git status
  -> hypa git status
  target = FirstClassCommand

dotnet test
  -> hypa dotnet test
  target = FirstClassCommand

some-custom-tool --check
  -> hypa -c "some-custom-tool --check"
  target = GenericCompressionWrapper

vim src/Foo.cs
  -> passthrough

kubectl logs -f pod/foo
  -> passthrough

HYPA_DISABLED=1 git status
  -> passthrough
```

--------------------------------

### Hypa Initialization and Health Check

Source: https://github.com/hypabolic/hypa/blob/main/src/Hypa.Infrastructure/Skills/Resources/HYPA.md

Run `hypa init --global` once to set up hooks and MCP. Use `hypa doctor` to verify the installation's health.

```bash
hypa init --global
```

```bash
hypa doctor
```

--------------------------------

### Local Development Installation

Source: https://github.com/hypabolic/hypa/blob/main/docs/guides/pi.md

Commands for installing the Hypa Pi package during local development from the repository. Use the `-e` flag for extension development or a direct path for standard installation.

```bash
pi -e ./packages/pi-hypa/extensions/index.ts
```

```bash
pi install ./packages/pi-hypa
```

--------------------------------

### Hypa Diagnostics Output Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Example output from the hypa_diagnostics tool, showing the runtime health and capability state.

```text
Hypa runtime: healthy
Session: active, project-bound, not Atomic-bound
Compression reducers: 8 loaded
Roslyn: available
Tree-sitter: available
Language servers: rust-analyzer healthy, pyright not found
Atomic: not authenticated
```

--------------------------------

### Hypa Doctor Command Examples

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/runtime-design.md

Shows example commands for using the 'hypa doctor' utility to diagnose specific runtime capabilities.

```bash
hypa doctor
hypa doctor code-intelligence
hypa doctor agents
hypa doctor shell
```

--------------------------------

### Install Hypa on Windows PowerShell

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Installs Hypa on Windows by downloading the latest release script via PowerShell and executing it.

```powershell
irm https://hypabolic.github.io/Hypa/install.ps1 | iex
```

--------------------------------

### Install Hypa Pi Package

Source: https://github.com/hypabolic/hypa/blob/main/docs/guides/pi.md

Use this command to install the Hypa Pi package from npm. This command also installs `@hypabolic/hypa` as a dependency.

```bash
pi install npm:@hypabolic/pi-hypa
```

--------------------------------

### Hypa Core Usage Examples

Source: https://github.com/hypabolic/hypa/blob/main/src/Hypa.Infrastructure/Skills/Resources/SKILL.md

Demonstrates the core usage of Hypa for compressing output from common development tools like Git, Dotnet, and Docker, as well as a generic command wrapper.

```bash
hypa git status
```

```bash
hypa dotnet build
```

```bash
hypa -c "any-cmd"
```

--------------------------------

### hypa_context Action: Pack Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Example arguments for the 'pack' action of the hypa_context tool, used to produce compact context packs for agents.

```json
{
  "action": "pack",
  "task": "Implement deterministic dotnet test compression",
  "maxTokens": 6000
}
```

--------------------------------

### Trust Command Examples

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0006-filter-dsl-and-parser-tiers.md

Provides example bash commands for managing trust settings related to project-local filters. These commands allow users to explicitly grant trust for filter execution.

```bash
hypa trust filters
hypa trust status
```

--------------------------------

### Install Kiota CLI Tool

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0007-sdk-multi-language-generation.md

Installs the Kiota CLI tool globally using the .NET CLI. This is a prerequisite for generating API clients.

```bash
# Install Kiota
dotnet tool install Microsoft.OpenApi.Kiota -g
```

--------------------------------

### Multiplexed Tool Call Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Demonstrates how a future meta-tool could multiplex subcommands for tools like 'read' and 'shell', and specific actions for 'code'.

```text
hypa(tool = "read", ...)
hypa(tool = "shell", ...)
hypa(tool = "code", action = "symbol", ...)
```

--------------------------------

### Build Hypa Project

Source: https://github.com/hypabolic/hypa/blob/main/README.md

These commands are used for building and testing the Hypa project from its source code. Ensure you have the .NET SDK installed.

```bash
dotnet build
```

```bash
dotnet test
```

```bash
dotnet format --verify-no-changes --no-restore
```

--------------------------------

### Example Language Server Candidates by Language

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0004-optional-language-server-enrichment.md

Provides a list of common language servers for various programming languages. This helps in identifying potential tools for enrichment.

```text
C#          csharp-ls, omnisharp
TypeScript  typescript-language-server, tsserver
Python      pyright-langserver, basedpyright-langserver, pylsp
Go          gopls
Rust        rust-analyzer
Java        jdtls
PHP         intelephense, phpactor
Ruby        ruby-lsp, solargraph
Terraform   terraform-ls
YAML        yaml-language-server
Docker      docker-langserver

```

--------------------------------

### Testing Scenarios for Command Rewriting

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Illustrative examples of command rewriting scenarios, including passthrough and generic wrapper cases.

```text
git status                         -> hypa git status
dotnet test --no-build             -> hypa dotnet test --no-build
custom-check --json                 -> hypa -c "custom-check --json"
HYPA_DISABLED=1 git status          -> passthrough
vim src/Foo.cs                      -> passthrough
kubectl logs -f pod/foo             -> passthrough
git status && dotnet test           -> hypa git status && hypa dotnet test
git log --oneline | head -20        -> hypa git log --oneline | head -20
cat input.txt > output.txt          -> passthrough
```

--------------------------------

### Hypa Session Initialization and Attachment Commands

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0001-local-context-runtime-operating-model.md

Provides example shell commands for initializing a new Hypa session and attaching it to an existing Atomic job and run. These commands demonstrate how to establish and link session context within the Hypa runtime.

```bash
hypa session init --agent-session-id <id>
hypa session attach --job-id <id> --run-id <id>
```

--------------------------------

### Initialize Hypa Globally

Source: https://github.com/hypabolic/hypa/blob/main/src/Hypa.Infrastructure/Skills/Resources/SKILL.md

Checks if Hypa is installed and initializes it globally if not found. Run this command to set up Hypa on your system.

```bash
which hypa || hypa init --global
```

--------------------------------

### hypa_code Action: References Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Example arguments for the 'references' action of the hypa_code tool, used to find where a specific symbol is referenced.

```json
{
  "action": "references",
  "symbol": "Hypa.Runtime.SessionManager.AttachAsync"
}
```

--------------------------------

### Canonical Test Cases: Generic Wrapper Commands

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Examples of commands that will be wrapped generically by Hypa when direct rewriting is not applicable.

```text
custom-check --json                 -> hypa -c "custom-check --json"
pnpm install                        -> hypa -c "pnpm install"
tsc --watch                         -> hypa -c "tsc --watch"
```

--------------------------------

### hypa_code Action: Symbols Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Example arguments for the 'symbols' action of the hypa_code tool, used for code intelligence queries.

```json
{
  "action": "symbols",
  "path": "src/Hypa.Runtime/SessionManager.cs"
}
```

--------------------------------

### Example Code Intelligence Diagnostics Output

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/code-intelligence.md

This is an example of the output you might see when running the code intelligence diagnostics command, showing the availability of different providers per language.

```text
C#:
  Roslyn: available
  Tree-sitter: available
  LSP: csharp-ls not found

TypeScript:
  Tree-sitter: available
  LSP: typescript-language-server found, healthy

Rust:
  Tree-sitter: available
  LSP: rust-analyzer found, healthy
```

--------------------------------

### Compound Command Rewrite Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0005-command-rewrite-registry.md

Shows how compound shell commands with operators like '&&' are rewritten at a segment level.

```text
cargo fmt --all && cargo test
  -> hypa cargo fmt --all && hypa cargo test

git log --oneline | head -20
  -> hypa git log --oneline | head -20
```

--------------------------------

### Environment Prefix Handling

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Examples of how Hypa handles environment variables and shell prefixes before matching commands, and how it re-applies them to the rewritten command.

```text
VAR=value git status
sudo git status
env VAR=value git status
command git status
noglob grep foo *.cs
```

--------------------------------

### Start Hypa Daemon and Manage Status

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/feature-parity-roadmap.md

Commands to start the Hypa daemon in the background, stop it, check its status, and view its logs. The daemon enables background telemetry collection.

```text
hypa serve -d              # start background daemon (Unix socket + PID file)
hypa serve stop
hypa daemon status
hypa daemon logs
hypa session watch         # list sessions the daemon is currently watching
```

--------------------------------

### Canonical Test Cases: Rewritten Commands

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Examples of common commands that are expected to be rewritten by Hypa.

```text
git status                         -> hypa git status
git diff HEAD~1                      -> hypa git diff HEAD~1
git log --oneline                  -> hypa git log --oneline
dotnet build                       -> hypa dotnet build
dotnet test                        -> hypa dotnet test
docker ps                          -> hypa docker ps
docker logs my-container           -> hypa docker logs my-container
kubectl get pods                   -> hypa kubectl get pods
kubectl describe pod my-pod        -> hypa kubectl describe pod my-pod
git status && dotnet build         -> hypa git status && hypa dotnet build
git status || dotnet build         -> hypa git status || hypa dotnet build
git status ; dotnet build          -> hypa git status ; hypa dotnet build
```

--------------------------------

### Parser Tier Examples for Different Tools

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0006-filter-dsl-and-parser-tiers.md

Illustrates how parser tiers (Full, Degraded, Passthrough) apply to common command-line tools like 'dotnet test', 'eslint', and 'go test'. This shows the expected parsing behavior for structured and unstructured output.

```text
dotnet test --logger trx
  Full: parse TRX or structured logger output
  Degraded: regex parse failing tests from text output
  Passthrough: safe truncation with [HYPA:PASSTHROUGH]

eslint --format json
  Full: parse JSON
  Degraded: parse stylish text output
  Passthrough: safe truncation

go test -json
  Full: parse NDJSON event stream
  Degraded: parse text output
  Passthrough: safe truncation
```

--------------------------------

### Language Server Fact Provenance Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/code-intelligence.md

Illustrates how to specify provenance for facts derived from language servers, indicating the provider, capability, and confidence level.

```text
provider = lsp:rust-analyzer
capability = references
confidence = semantic
```

--------------------------------

### Pipe Command Rewrite Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Illustrates Hypa's conservative approach to rewriting commands involving pipes, typically only optimizing the left-hand side.

```text
git log --oneline | head -20
  -> hypa git log --oneline | head -20
```

--------------------------------

### Canonical Test Cases: Passthrough Commands

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Examples of commands that are explicitly configured to pass through Hypa's rewriting process.

```text
vim file.cs                         -> (passthrough)
git push origin main                -> (passthrough)
cat file | grep foo                 -> (passthrough)
kubectl logs -f pod/foo             -> (passthrough)
```

--------------------------------

### EvidenceRecord Examples

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/data-model.md

Illustrates various types of evidence records that can be generated, categorized by source and nature of the observation.

```text
tool:ctx_shell
tool:ctx_shell:dotnet-test
file:read:src/Hypa.Runtime/SessionManager.cs
diagnostic:cs:CS8602
decision:compression:deterministic-default
finding:code-index:tree-sitter-supported
```

--------------------------------

### LSP Fact Provenance Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0004-optional-language-server-enrichment.md

Illustrates how to attach provenance information to facts derived from Language Server Protocol. This helps track the source and capability used.

```text
provider = lsp
serverId = rust-analyzer | gopls | pyright | ...
capability = definition | references | diagnostics | ...
confidence = semantic

```

--------------------------------

### TOML Configuration for Code Intelligence and Language Servers

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0004-optional-language-server-enrichment.md

Shows example TOML configuration settings for enabling different code intelligence providers and specifying trusted language servers.

```toml
[code_intelligence]
roslyn = true
tree_sitter = true
language_servers = "trusted-only"

[language_servers.trusted]
rust_analyzer = true
gopls = true
pyright = true
typescript_language_server = true

```

--------------------------------

### Claude/Cursor-style Input for Rewritten Command

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Example of input JSON structure for tools like Claude or Cursor, specifying a command to be rewritten.

```json
{
  "tool_name": "Bash",
  "tool_input": { "command": "git status" }
}
```

--------------------------------

### hypa_session Action: Attach Arguments

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Example arguments for the 'attach' action of the hypa_session tool, used to manage local session state.

```json
{
  "action": "attach",
  "atomicAgentSessionId": "...",
  "jobId": "...",
  "runId": "...",
  "stepId": "..."
}
```

--------------------------------

### Hypa CLI Commands for LLM Proxy Mode

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/feature-parity-roadmap.md

Commands to start, stop, and check the status of the Hypa LLM proxy, which intercepts HTTP traffic for transparent compression.

```text
hypa proxy start        # local proxy on configurable port (default: 4723)
hypa proxy stop
hypa proxy status
```

--------------------------------

### Override Installer Variables in PowerShell

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Customizes Hypa installation on Windows by setting environment variables for version and installation directory before running the install script.

```powershell
$env:HYPA_VERSION = "0.1.0"
$env:HYPA_INSTALL_DIR = "$HOME\bin"
irm https://raw.githubusercontent.com/Hypabolic/Hypa/main/install.ps1 | iex
```

--------------------------------

### Runtime Entry Points Overview

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/runtime-design.md

Lists the different ways to interact with the Hypa runtime, including CLI, MCP Server, Shell Hook, Agent Adapters, and Background Service.

```text
hypa CLI
  direct human use, setup, diagnostics, indexing, shell wrapping

Hypa MCP Server
  structured agent tools over stdio or HTTP/SSE where supported

Shell Hook / Wrapper
  command execution tracking and deterministic output compression

Agent Hook Adapters
  host-specific PreToolUse / command rewrite / session start integration

Background Service
  optional long-lived local daemon for caching, indexing, language server management, and Atomic sync
```

--------------------------------

### Override Installer Variables

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Allows customization of the Hypa installation process by setting environment variables for version and installation directory.

```bash
HYPA_VERSION=0.1.0 HYPA_INSTALL_DIR="$HOME/bin" sh install.sh
```

```bash
HYPA_VERSION=v0.1.0 HYPA_REPO=owner/Hypa sh install.sh
```

--------------------------------

### Build Hypa from Source

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Builds the Hypa CLI project using the .NET SDK. Requires .NET 10 SDK and a compatible shell environment.

```bash
dotnet build src/Hypa.Cli/Hypa.Cli.csproj
```

--------------------------------

### Run Hypa Help from Source

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Executes the Hypa CLI with the --help flag when built from source, displaying available commands and options.

```bash
dotnet run --project src/Hypa.Cli -- --help
```

--------------------------------

### Use First-Class Command Wrappers

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Leverages Hypa's built-in wrappers for common developer tools like git, dotnet, kubectl, and docker to automatically process their output.

```bash
hypa git status
```

```bash
hypa dotnet build
```

```bash
hypa kubectl get pods
```

```bash
hypa docker ps
```

--------------------------------

### Agent Instructions for Hosts

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Provides a set of recommended instructions for agents operating on supported hosts, emphasizing the use of specific Hypa tools for different tasks.

```text
Use hypa_read instead of repeatedly reading large files.
Use hypa_shell for build/test commands.
Use hypa_code for symbols, references, and graph questions.
Record durable findings and decisions through hypa_session.
Attach job/run/step IDs when available.
```

--------------------------------

### Initialize Hypa for Agent Harness

Source: https://github.com/hypabolic/hypa/blob/main/npm/hypa/README.md

Initializes Hypa globally to integrate with your agent harness.

```bash
hypa init --global
```

--------------------------------

### Example Markdown Savings Table

Source: https://github.com/hypabolic/hypa/blob/main/README.md

This is an example of the Markdown table output generated by Hypa for savings reports. It clearly lists filter details, original and compressed token counts, and savings.

```markdown
| Filter | Applies | Original Tokens | Compressed Tokens | Saved Tokens | Saved |
|---|---:|---:|---:|---:|---:|
| dotnet-msbuild-noise | dotnet | 635 | 5 | 630 | 99% |
| **TOTAL** |  | **635** | **5** | **630** | **99%** |
```

--------------------------------

### Custom Filter DSL Example

Source: https://github.com/hypabolic/hypa/blob/main/src/Hypa.Infrastructure/Skills/Resources/SKILL.md

An example of a custom filter definition using JSON format. This filter is named 'my-filter' and includes a single stage that uses 'grep' to find lines containing 'error' or 'warning'.

```json
{
  "name": "my-filter",
  "stages": [{"kind": "grep", "pattern": "error|warning"}]
}
```

--------------------------------

### Launch Local Observability Dashboard

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/feature-parity-roadmap.md

Launches the local web-based dashboard for Hypa metrics on localhost.

```text
hypa dashboard
```

--------------------------------

### Output JSON when Command is Rewritten

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Example of the output JSON structure when a command has been successfully rewritten by Hypa.

```json
{
  "hookSpecificOutput": {
    "updatedInput": { "command": "hypa git status" }
  }
}
```

--------------------------------

### Get Dashboard Stats as JSON

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/feature-parity-roadmap.md

Retrieves a machine-readable snapshot of the current dashboard statistics in JSON format.

```text
hypa dashboard --json
```

--------------------------------

### Redirect Preservation Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Shows how Hypa can preserve trailing redirects, such as standard error redirection, when rewriting commands.

```text
git status 2>&1
  -> hypa git status 2>&1
```

--------------------------------

### Suggested Local Configuration Paths

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/runtime-design.md

Provides common file paths for local Hypa configuration files, including user-specific and project-specific locations.

```text
~/.hypa/config.toml
<project>/.hypa/config.toml
<project>/.hypa/session.json
```

--------------------------------

### Initialize Hypa with Pi Agent

Source: https://github.com/hypabolic/hypa/blob/main/docs/guides/pi.md

This command initializes Hypa and configures it to use Pi as its agent. This is useful for setting up Hypa within a Pi environment.

```bash
hypa init --agent pi
```

--------------------------------

### Initial Hypa Tool Set

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

Lists the core tools initially exposed by Hypa. These are fundamental utilities for agent interaction.

```text
hypa_session
hypa_shell
hypa_read
hypa_search
hypa_code
hypa_context
hypa_compress
hypa_diagnostics
```

--------------------------------

### Suggested CLI Commands for Language Server Management

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0004-optional-language-server-enrichment.md

Outlines command-line interface commands for managing and querying language server status within Hypa. Useful for diagnostics and control.

```bash
hypa doctor code-intelligence
hypa scan-language-servers
hypa index --with-lsp

```

--------------------------------

### Generic Wrapper Fallback Command

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Demonstrates the fallback command format used by Hypa when a command does not have a first-class reducer, wrapping the original command for compression.

```bash
hypa -c "<original command>"
```

--------------------------------

### Run and Compress a Command with Hypa

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Executes the 'dotnet test' command through Hypa, which compresses the output and applies reducers/filters.

```bash
hypa -c "dotnet test"
```

--------------------------------

### Recommended Tool Output Format

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/mcp-and-tools.md

The recommended structured format for tool outputs to ensure they are compact and agent-actionable.

```text
SUMMARY
<short result>

DETAILS
<important facts>

REFERENCES
<artifact refs, file refs, symbol refs>

STATS
<tokens, compression, duration where useful>
```

--------------------------------

### Decorator Pattern: Tracked Compressor Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/engineering-principles.md

Adds cross-cutting concerns like timing and metrics recording to a Port implementation. Wraps an existing ICommandOutputCompressor.

```csharp
// Adds timing and token savings recording around any compressor
public sealed class TrackedCompressor(ICommandOutputCompressor inner, IMetricsRecorder metrics)
    : ICommandOutputCompressor { ... }
```

--------------------------------

### Repository Pattern: Session Repository Interface and Implementation

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/engineering-principles.md

Defines the application port for session persistence and an example of an infrastructure adapter. Used for all persistence operations.

```csharp
// Application Port
public interface ISessionRepository
{
    Task<ContextSession?> FindLatestAsync(string projectRoot, CancellationToken ct);
    Task SaveAsync(ContextSession session, CancellationToken ct);
}

// Infrastructure Adapter
public sealed class SqliteSessionRepository : ISessionRepository { ... }
```

--------------------------------

### Run a Command Through Hypa from Source

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Executes a 'dotnet build' command using Hypa when built from source. This demonstrates running a command with Hypa's processing pipeline.

```bash
dotnet run --project src/Hypa.Cli -- -c "dotnet build"
```

--------------------------------

### Hypa CLI Wrappers

Source: https://github.com/hypabolic/hypa/blob/main/src/Hypa.Infrastructure/Skills/Resources/HYPA.md

Use Hypa wrappers for direct CLI tool invocation to leverage Hypa's features like compression and session tracking.

```bash
hypa git <args>
```

```bash
hypa dotnet <args>
```

```bash
hypa docker <args>
```

```bash
hypa kubectl <args>
```

--------------------------------

### Command Pattern: Doctor Command Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/engineering-principles.md

Represents a CLI subcommand as a discrete class. The command class handles argument parsing and calls the appropriate application service.

```csharp
public sealed class DoctorCommand
{
    private readonly DoctorService _service;
    public DoctorCommand(DoctorService service) => _service = service;
    public Command Build() { ... } // returns System.CommandLine Command
}
```

--------------------------------

### Run CLI from Source

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Execute the Hypa CLI directly from the source code using `dotnet run`. This is useful for development and testing changes before building a distributable package.

```bash
dotnet run --project src/Hypa.Cli -- filters savings --markdown
```

--------------------------------

### Command Execution Flow with Rewriting and Compression

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/command-rewrite.md

Diagrammatic representation of the command execution pipeline, showing the sequence from rewrite to compressed output.

```text
rewrite -> command runner -> parser/reducer/filter -> compressed output -> tracking/evidence
```

--------------------------------

### Configuration Loading Sources

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/runtime-design.md

Outlines the layered sources from which Hypa loads its configuration, from built-in defaults to agent/session bindings.

```text
built-in defaults
user config
project config
workspace config
environment variables
CLI arguments
agent/session binding
```

--------------------------------

### Telemetry Model Mapping Example

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0008-telemetry-model-boundaries.md

Illustrates the mapping of internal Hypa records to SDK event types and JSON payloads. This mapping is handled by a dedicated service in Hypa's sync path.

```text
CommandMetricsRecord  →  HypaCommandEventV1   →  JsonObject  →  AddEventInput
ToolCallMetricsRecord →  HypaToolCallEventV1  →  JsonObject  →  AddEventInput
FileTouchRecord       →  HypaFileTouchEventV1 →  JsonObject  →  AddEventInput
ContextSession        →  HypaSessionEventV1   →  JsonObject  →  AddEventInput
CodeIndexResult       →  HypaCodeIndexedEventV1 → JsonObject →  AddEventInput
-- Phase 5 --
FileReadMetricsRecord →  HypaFileReadEventV1  →  JsonObject  →  AddEventInput
FileWriteMetricsRecord → HypaFileWriteEventV1 →  JsonObject  →  AddEventInput
-- Phase 9B / 13 --
AgentTurnRecord       →  HypaAgentTurnEventV1 →  JsonObject  →  AddEventInput
```

--------------------------------

### Estimate Savings for Built-in Filters

Source: https://github.com/hypabolic/hypa/blob/main/README.md

Run this command to get a broad estimate of savings for Hypa's built-in filter suite without executing real infrastructure commands. This is useful for initial coverage checks.

```bash
hypa filters savings
```

--------------------------------

### Hypa CLI Commands for Phase 9 Agent Integration

Source: https://github.com/hypabolic/hypa/blob/main/docs/architecture/feature-parity-roadmap.md

Commands for initializing and managing Hypa integrations with various agent harnesses.

```text
hypa init --agent claude
hypa init --agent cursor
hypa init --agent codex
hypa init --agent copilot
hypa init --agent windsurf
hypa init --agent kiro
hypa hooks status
hypa hooks uninstall
```

--------------------------------

### Atomic Deserializing Hypa SDK Telemetry Event

Source: https://github.com/hypabolic/hypa/blob/main/docs/ADRs/0008-telemetry-model-boundaries.md

Example of how Atomic deserializes incoming Hypa SDK telemetry events using C#. This code snippet demonstrates type-safe deserialization and accessing specific payload fields.

```csharp
// In Atomic's memory synthesis or analytics layer
if (evt.EventType == HypaEventTypes.CommandCompressed)
{
    var payload = evt.Payload.Deserialize<HypaCommandEventV1>(options);
    var tokensSaved = payload.OriginalTokens - payload.CompressedTokens;
    // ... synthesise memory or update run stats
}
```