Skip to content
Back to search

Hypa

Hypa is a workspace for coding agents. It runs your agents in terminal panes, keeps them alive when you close the terminal, lets agents drive other panes, and cuts the noise from command output…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hypabolic--hypa/badge.svg)](/listings/hypabolic--hypa)

HTML

<a href="/listings/hypabolic--hypa"><img src="/api/listings/hypabolic--hypa/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Pick the channel that fits how you manage tools. Every channel installs the same release archive for your platform, so the mux works the same way in each.

| Channel | Command | Update with | | --- | --- | --- | | Install script | `curl -fsSL https://raw.githubusercontent.com/Hypabolic/Hypa/main/install.sh \| sh` | `hypa update` | | Homebrew | `brew install hypabolic/tap/hypa` | `brew upgrade hypa` | | npm | `npm install --global @hypabolic/hypa` | `npm install --global @hypabolic/hypa@latest` | | PyPI | `pipx install hypa` | `pipx upgrade hypa` | | Release archive | Download from [GitHub Releases](https://github.com/Hypabolic/Hypa/releases) | Download again | | Source | [Build from source](#build-from-source) | `git pull` and build again |

Releases from 1.0.1 on are published to Homebrew, npm, and PyPI. Version 1.0.0 is available only as a release archive and through the install script.

Install one copy. If you switch channels, remove the old copy first, so that only one `hypa` is on your `PATH`.

Check any install:

hypa --version
hypa doctor

Requirements

| Platform | Needs | | --- | --- | | Linux x64 or arm64 | glibc 2.34 or newer. Alpine and other musl systems are not supported. | | macOS x64 or arm64 | macOS 12 or newer. | | Windows | Not a mux host. See [Windows](#windows). |

The npm package needs Node.js 18 or newer. The PyPI package needs Python 3.9 or newer. Neither needs a .NET runtime.

Install script

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/Hypabolic/Hypa/main/install.sh | sh

The installer downloads the release archive for your platform, checks it against `SHA256SUMS`, and installs `hypa` in a bin directory that you can write to (`~/.local/bin` by default). It prints a warning when that directory is not on your `PATH`.

Installer options:

HYPA_VERSION=1.0.1 HYPA_INSTALL_DIR="$HOME/bin" sh install.sh
HYPA_ARCHIVE=/path/to/hypa-osx-arm64.tar.gz HYPA_INSTALL_DIR="$HOME/bin" HYPA_APP_DIR="$HOME/share/hypa" sh install.sh

Homebrew

macOS and Linux:

brew install hypabolic/tap/hypa

This adds the `hypabolic/tap` tap and installs the formula. Homebrew keeps the whole release directory in the Cellar and links `hypa` into your `PATH`.

npm

npm install --global @hypabolic/hypa

The `@hypabolic/hypa` package picks the matching platform package, for example `@hypabolic/hypa-darwin-arm64`, as an optional dependency. If your package manager skips optional dependencies, install the platform package yourself.

PyPI

pipx install hypa
# or
uv tool install hypa
# or
pip install hypa

Prefer `pipx` or `uv tool`, which keep `hypa` out of your project environments. The wheel carries the native build, and the `hypa` command starts it.

Release archive

Download the archive for your platform from [GitHub Releases](https://github.com/Hypabolic/Hypa/releases), together with `SHA256SUMS`, and check the archive against it.

| Platform | Archive | | --- | --- | | Linux x64 | `hypa-linux-x64.tar.gz` | | Linux arm64 | `hypa-linux-arm64.tar.gz` | | macOS x64 | `hypa-osx-x64.tar.gz` | | macOS arm64 | `hypa-osx-arm64.tar.gz` |

The archive unpacks to a `hypa-<platform>` directory. Keep its files together: `hypa` finds the mux host, the attach client, and its native libraries next to itself. Run `hypa` from that directory, or link it into a directory on your `PATH`.

Update

`hypa update --check` shows whether a newer release exists. `hypa update` upgrades a copy that the install script put in place. For a copy that a package manager installed, it prints the command to run:

| Installed with | Upgrade with | | --- | --- | | Homebrew | `brew upgrade hypa` | | npm | `npm install --global @hypabolic/hypa@latest` | | pipx | `pipx upgrade hypa` | | uv | `uv tool upgrade hypa` | | pip | `python3 -m pip install --upgrade hypa` |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 332 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <img width="1169" height="581" alt="Hypa" src="https://github.com/user-attachments/assets/f8390eab-a3b7-4227-9c8e-da61d2b3663d" />
  2. # Hypa
  3. Hypa is a workspace for coding agents. It runs your agents in terminal panes, keeps them alive when you close the terminal, lets agents drive other panes, and cuts the noise from command output before it reaches an agent.
  4. Hypa is local-first. It needs no cloud service.
  5. ## What Hypa does
  6. - **Workspace mux.** `hypa` starts a local server that owns your panes. Attach from any terminal, detach, and attach again. Tabs, splits, workspaces, a sidebar, copy mode, popups, themes, and settings are built in.
  7. - **Agent runtime.** An agent in a Hypa pane can read other panes, start work in a new pane or a hidden pane, wait for another agent, and report its state. Hypa installs a skill that teaches an agent how.
  8. - **Share and connect.** Share a session with another machine. The other machine connects over QUIC, with TCP and TLS as the fallback. A certificate pin protects every connection.
  9. - **Output compression.** `hypa -c "command"` runs a command, removes noise from the output, and keeps what matters: errors, warnings, file paths, failing tests, and exit codes. The reduction is deterministic and local. It is not an LLM summary.
  10. ## Install
  11. Pick the channel that fits how you manage tools. Every channel installs the same release archive for your platform, so the mux works the same way in each.
  12. | Channel | Command | Update with |
  13. | --- | --- | --- |
  14. | Install script | `curl -fsSL https://raw.githubusercontent.com/Hypabolic/Hypa/main/install.sh \| sh` | `hypa update` |
  15. | Homebrew | `brew install hypabolic/tap/hypa` | `brew upgrade hypa` |
  16. | npm | `npm install --global @hypabolic/hypa` | `npm install --global @hypabolic/hypa@latest` |
  17. | PyPI | `pipx install hypa` | `pipx upgrade hypa` |
  18. | Release archive | Download from [GitHub Releases](https://github.com/Hypabolic/Hypa/releases) | Download again |
  19. | Source | [Build from source](#build-from-source) | `git pull` and build again |
  20. Releases from 1.0.1 on are published to Homebrew, npm, and PyPI. Version 1.0.0 is available only as a release archive and through the install script.
  21. Install one copy. If you switch channels, remove the old copy first, so that only one `hypa` is on your `PATH`.
  22. Check any install:
  23. ```bash
  24. hypa --version
  25. hypa doctor
  26. ```
  27. ### Requirements
  28. | Platform | Needs |
  29. | --- | --- |
  30. | Linux x64 or arm64 | glibc 2.34 or newer. Alpine and other musl systems are not supported. |
  31. | macOS x64 or arm64 | macOS 12 or newer. |
  32. | Windows | Not a mux host. See [Windows](#windows). |
  33. The npm package needs Node.js 18 or newer. The PyPI package needs Python 3.9 or newer. Neither needs a .NET runtime.
  34. ### Install script
  35. Linux and macOS:
  36. ```bash
  37. curl -fsSL https://raw.githubusercontent.com/Hypabolic/Hypa/main/install.sh | sh
  38. ```
  39. The installer downloads the release archive for your platform, checks it against `SHA256SUMS`, and installs `hypa` in a bin directory that you can write to (`~/.local/bin` by default). It prints a warning when that directory is not on your `PATH`.
  40. Installer options:
  41. ```bash
  42. HYPA_VERSION=1.0.1 HYPA_INSTALL_DIR="$HOME/bin" sh install.sh
  43. HYPA_ARCHIVE=/path/to/hypa-osx-arm64.tar.gz HYPA_INSTALL_DIR="$HOME/bin" HYPA_APP_DIR="$HOME/share/hypa" sh install.sh
  44. ```
  45. ### Homebrew
  46. macOS and Linux:
  47. ```bash
  48. brew install hypabolic/tap/hypa
  49. ```
  50. This adds the `hypabolic/tap` tap and installs the formula. Homebrew keeps the whole release directory in the Cellar and links `hypa` into your `PATH`.
  51. ### npm
  52. ```bash
  53. npm install --global @hypabolic/hypa
  54. ```
  55. The `@hypabolic/hypa` package picks the matching platform package, for example `@hypabolic/hypa-darwin-arm64`, as an optional dependency. If your package manager skips optional dependencies, install the platform package yourself.
  56. ### PyPI
  57. ```bash
  58. pipx install hypa
  59. # or
  60. uv tool install hypa
  61. # or
  62. pip install hypa
  63. ```
  64. Prefer `pipx` or `uv tool`, which keep `hypa` out of your project environments. The wheel carries the native build, and the `hypa` command starts it.
  65. ### Release archive
  66. Download the archive for your platform from [GitHub Releases](https://github.com/Hypabolic/Hypa/releases), together with `SHA256SUMS`, and check the archive against it.
  67. | Platform | Archive |
  68. | --- | --- |
  69. | Linux x64 | `hypa-linux-x64.tar.gz` |
  70. | Linux arm64 | `hypa-linux-arm64.tar.gz` |
  71. | macOS x64 | `hypa-osx-x64.tar.gz` |
  72. | macOS arm64 | `hypa-osx-arm64.tar.gz` |
  73. The archive unpacks to a `hypa-<platform>` directory. Keep its files together: `hypa` finds the mux host, the attach client, and its native libraries next to itself. Run `hypa` from that directory, or link it into a directory on your `PATH`.
  74. ### Update
  75. `hypa update --check` shows whether a newer release exists. `hypa update` upgrades a copy that the install script put in place. For a copy that a package manager installed, it prints the command to run:
  76. | Installed with | Upgrade with |
  77. | --- | --- |
  78. | Homebrew | `brew upgrade hypa` |
  79. | npm | `npm install --global @hypabolic/hypa@latest` |
  80. | pipx | `pipx upgrade hypa` |
  81. | uv | `uv tool upgrade hypa` |
  82. | pip | `python3 -m pip install --upgrade hypa` |
  83. After an upgrade, a running mux server still runs the old version. When you next attach, Hypa offers to restart it. While you are attached, the sidebar shows **↻ restart to update**; click it to restart the mux and reattach on the new version. From a terminal outside Hypa, run `hypa mux restart`. A restart closes every pane.
  84. ### Windows
  85. Windows is not a mux host. There is no Windows mux archive, and `install.ps1` stops with an error. The compression CLI can still run on Windows. Build it from source (see below).
  86. ## Quick start
  87. ```bash
  88. hypa
  89. ```
  90. Bare `hypa` starts the local mux server, or reconnects to it, and attaches. The first run shows an onboarding overlay.
  91. Keys use a prefix, `ctrl+b` by default:
  92. | Keys | Action |
  93. | --- | --- |
  94. | `prefix` then `?` | List the active key bindings. Press `/` to filter. |
  95. | `prefix` then `q` | Detach. The server and your panes keep running. |
  96. | `prefix` then `s` | Open settings. |
  97. Close the terminal, or detach, and attach again with `hypa`. Panes keep running while you are away.
  98. Install the agent integration. Hypa finds the agents on your machine and shows every file it writes before it writes:
  99. ```bash
  100. hypa integration install
  101. hypa integration status
  102. ```
  103. `hypa init` installs hooks and skills for the detected agent harnesses. Use `--dry-run` to preview either command.
  104. ## Workspace mux
  105. A session holds workspaces, each workspace holds tabs, and each tab holds panes. One mux server owns one session.
  106. ```bash
  107. hypa --session NAME # attach to a named session
  108. hypa session list
  109. hypa session attach NAME
  110. hypa session stop NAME
  111. hypa session delete NAME
  112. hypa status # mux client and server status
  113. hypa mux serve --session default # run the server without attaching
  114. hypa mux stop
  115. hypa mux restart # stop, then start on the installed version
  116. ```
  117. `hypa ping`, `hypa snapshot`, `hypa workspace`, `hypa tab`, `hypa pane`, and `hypa layout` talk to a running server. They do not start it.
  118. Attach to a mux on another machine through OpenSSH:
  119. ```bash
  120. hypa --remote user@host
  121. hypa --remote user@host --session NAME
  122. ```
  123. OpenSSH owns keys and credentials. Hypa stores none. See [`docs/guides/remote-ssh-attach.md`](docs/guides/remote-ssh-attach.md).
  124. Panes use a real PTY and the Ghostty terminal engine. Hypa paints one composed frame for your terminal. The host palette, focus events, mouse, and bracketed paste reach the panes, and arrow, Home, and End keys use the form that the running program asks for.
  125. Customize Hypa in `~/.config/hypa/config.toml`:
  126. ```bash
  127. hypa --default-config # print the default file
  128. hypa config check # validate your file
  129. ```
  130. There are 19 built-in themes. An invalid value in the file stops Hypa with an error. It does not fall back in silence.
  131. A saved screen history for restored panes is off by default. See [`docs/guides/session-state.md`](docs/guides/session-state.md).
  132. ## Agent runtime
  133. Every pane child gets `HYPA_ENV=1`, `HYPA_BIN_PATH`, `HYPA_RUNTIME_SOCKET`, and pane identity keys. An agent uses the `hypa` command with those keys to control the session. See [`docs/guides/pane-environment.md`](docs/guides/pane-environment.md).
  134. ```bash
  135. hypa --skill # print the agent skill
  136. hypa pane --help # pane operations for scripts and agents
  137. hypa api schema --json # the control-plane protocol
  138. ```
  139. What an agent can do:
  140. - Inspect workspaces, tabs, panes, and agents.
  141. - Split a pane and run a command, then read its output or wait for it.
  142. - Start another agent in a new pane.
  143. - Create a **hidden pane** for background work. A hidden pane has a live PTY and no place in the layout. You can show, hide, and read it from the attach view. See [`docs/guides/background-panes.md`](docs/guides/background-panes.md).
  144. The skill is installed for the agents that Hypa detects. See [`docs/guides/agent-skill.md`](docs/guides/agent-skill.md). Hypa supports many agent harnesses, including Claude, Codex, Copilot, Cursor, Grok, Pi, and others. Run `hypa integration install --help` for the list.
  145. A plugin runs as your user with full permissions. It is not a sandbox.
  146. ## Share and connect
  147. Open the share dialog in the attach view to make an invite. The invite carries every reachable address of your machine, so you do not set an address first. The other machine redeems the invite, tries each address, and reports the address that answered.
  148. - QUIC is the first path. TCP with TLS is the fallback.
  149. - A certificate pin protects every connection. The secret is sent only after the pin matches.
  150. - A saved peer is a **cube**. Connect moves your view to that peer.
  151. - The mux owns the share. Closing the attach that started it does not stop it, and the mux starts it again after a restart. Press stop in the share dialog to end it. See [`docs/guides/share-lifetime.md`](docs/guides/share-lifetime.md).
  152. - `hypa connectivity accept` runs the listening side by hand. `hypa device` pairs and revokes devices.
  153. An invite holds at most 32 addresses. Use `--advertise-host` to name one address. See [`docs/guides/share-invite.md`](docs/guides/share-invite.md) and [`docs/guides/connectivity-accept.md`](docs/guides/connectivity-accept.md).
  154. ## Output compression
  155. Hypa runs a command, reduces the output, and returns a compact result:
  156. ```text
  157. shell command
  158. -> Hypa command runner
  159. -> command-specific reducer, when available
  160. -> built-in or trusted DSL filter, when applicable
  161. -> token accounting and savings metadata
  162. -> compact output returned to the caller
  163. ```
  164. If the result saves tokens, Hypa appends a footer:
  165. ```text
  166. [hypa: 1200→340 tok, -72%, reducer=dotnet-build]
  167. ```
  168. <img width="1272" height="744" alt="Hypa output compression" src="https://github.com/user-attachments/assets/ed7bcd40-041e-4be7-a575-fc9af814d64d" />
  169. For failures or truncation, Hypa can tee the full output to a local artifact, so the compact output stays small and you can still recover everything.
  170. ```bash
  171. hypa -c "dotnet test" # run and compress
  172. hypa -t dotnet test # run unmodified, streamed to the terminal
  173. hypa git status # first-class wrappers: git, dotnet, kubectl, docker
  174. hypa rewrite "git status" # show how a command would be rewritten
  175. hypa filters list # built-in and configured filters
  176. hypa filters test NAME ./output.txt # test a filter against a saved output
  177. hypa filters savings --markdown # estimate savings for the filter suite
  178. hypa read PATH # read a file in a context-aware mode
  179. hypa search QUERY # search files, symbols, and indexed context
  180. hypa code # index and query source code structure
  181. hypa compress # compress text from stdin or a file
  182. ```
  183. Built-in filters cover build and test tools (`dotnet`, `cargo`, `gradle`, `mvn`, `go test`, `jest`, `pytest`, `xcodebuild`), package managers (`npm`, `pnpm`, `yarn`, `pip`, `poetry`, `uv`), linters, infrastructure tools (`terraform`, `helm`, `kubectl`, `docker`, `aws`, `gcloud`), system tools, monorepo task runners, and source control. Run `hypa filters list` for the current list.
  184. Token estimates use `Microsoft.ML.Tokenizers` with the `o200k_base` tokenizer. Savings reports use synthetic payloads. Treat them as repeatable estimates, not as a measure of your own projects.
  185. Hypa runs trusted project filters from a repository `.hypa/` directory. It does not run every repository filter on its own. Use `hypa trust status` and `hypa trust filters`.
  186. Hypa also works as an MCP server (`hypa serve`) and through agent hooks (`hypa hook`, installed by `hypa init`). The Pi extension has its own guide: [`docs/guides/pi.md`](docs/guides/pi.md).
  187. ## Local data
  188. Hypa keeps runtime data in `~/.hypa/`:
  189. - `hypa.db`: SQLite database with sessions, command metrics, parse metrics, trust records, and artifacts.
  190. - `artifacts/`: full command output, kept for recovery.
  191. - `config.json`: optional compression configuration.
  192. The mux configuration is `~/.config/hypa/config.toml`. It is a separate file from `config.json`. Do not merge them.
  193. ## Platforms and limits
  194. - Linux and macOS are the mux hosts (`linux-x64`, `linux-arm64`, `osx-x64`, `osx-arm64`).
  195. - Windows is not a mux host. See [`docs/ADRs/0015-windows-is-not-a-mux-host.md`](docs/ADRs/0015-windows-is-not-a-mux-host.md).
  196. - A running mux keeps the binary that started it. After an upgrade, stop the old mux and start it again.
  197. - QUIC does not start when you bind `hypa connectivity accept` to a specific address. That accept uses TCP with TLS.
  198. ## Build from source
  199. You need the .NET 10 SDK. Linux or macOS is required for the mux.
  200. ```bash
  201. dotnet build
  202. dotnet test
  203. dotnet format --verify-no-changes --no-restore
  204. dotnet run --project src/Hypa.Cli -- --help
  205. ```
  206. Publish a local binary (Linux x64 example):
  207. ```bash
  208. dotnet publish src/Hypa.Cli/Hypa.Cli.csproj -c Release -r linux-x64
  209. ```
  210. The executable is written under `src/Hypa.Cli/bin/Release/net10.0/linux-x64/publish/`. Put that directory on your `PATH`, or link the executable as `hypa`.
  211. To run the current working tree as your `hypa` command while a release is installed, use the preview helper:
  212. ```bash
  213. scripts/hypa-preview install --test # publish, test, and switch to the preview
  214. scripts/hypa-preview install --fast # skip tests and NativeAOT
  215. scripts/hypa-preview status
  216. scripts/hypa-preview restore # switch back to the release
  217. ```
  218. While a preview is active, `hypa update` does not replace it.
  219. ## Documentation
  220. - [`docs/guides/`](docs/guides/): how-to guides for the mux, the agent skill, panes, sharing, and remote attach.
  221. - [`docs/architecture/`](docs/architecture/) and [`docs/ADRs/`](docs/ADRs/): design and decisions.
  222. - [`docs/release-notes/`](docs/release-notes/): release notes.
  223. ## Status
  224. Hypa 1.0.0 is the first release with the workspace mux and the agent runtime. Report faults at <https://github.com/Hypabolic/Hypa/issues>.
  225. ## License
  226. Hypa is licensed under the Functional Source License, Version 1.1, with an Apache 2.0 future license. See `license.md` in the public repository.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.