Files
hyperframes/skills/hyperframes/references/plugin-installation.md
T
Michael Wang d5f0b1a5bf fix: nested .hyperframes stays private, capture page server checks Host, project manifests pin no CLI (#7927)
* fix(core): a .hyperframes folder in a subfolder stays private too

The private-file rule treated .hyperframes as the app's records folder only at
the project root. A project copied into a subfolder keeps its own
.hyperframes/, and its chat history, hand-off and other records there were
listed in the file tree and served by Studio's file and preview routes and by
the other file servers that share the rule.

A .hyperframes segment at any depth is now private, in every spelling Windows
opens. Studio's own files and the prepared-assets and requests folders stay
servable only at the root, the one place Studio reads and writes them. The file
tree also skips .hyperframes/backup at any depth.

* fix(cli): the capture --local-file page server answers only its own host

The page server that capture --local-file starts on a loopback port answered a
request whatever its Host header said. A site whose name resolves to 127.0.0.1
could then read the files it serves from the browser.

The server now refuses, before any file lookup, a request whose Host is not its
own loopback name and port, with the same isOwnLoopbackHost rule the static
project server and the engine file server use. Every response carries
X-Content-Type-Options: nosniff. The capture browser loads the page by
127.0.0.1 and its port, and fetchLocalPageUrl reads from disk, so both work as
before.

* fix(skills): a plugin manifest in the project pins no CLI release

The skills launcher read a plugin manifest from the folder above skills/
wherever the skills were installed. For a project-level install that folder is
the project itself or its .agents or .claude folder, so a plugin.json shipped
with a project could pin an old hyperframes release and turn off update checks
and standalone skill refreshes.

The launcher now reads a manifest only from a bundle of its own: a folder whose
name does not start with a dot and that is neither the folder the CLI works in
nor one that contains it. Plugin managers install bundles into their own
folders, so those keep their pin. A manifest anywhere else leaves the call the
same as with no manifest. A manifest that pins a release older than 0.9.34, the
launcher's floor, is refused. The agent-facing plugin rules and the skills
guide say the same.

* fix(skills): a plugin bundle inside the working folder pins only behind a dot folder

A package inside a monorepo could still pin the CLI: with the agent working at
the monorepo root, <mono>/packages/video/plugin.json sat beside a skills folder
the launcher took for a bundle.

The launcher now also refuses a bundle inside the working folder unless a
folder whose name starts with a dot lies between them, as .claude does in
~/.claude/plugins/cache when the agent works in the home folder. Bundles in
~/.claude/plugins, ~/.cursor/plugins and ~/.gemini/extensions keep their pin
from the home folder or a project. The plugin rules and the skills guide now
state the three conditions the launcher checks.

* docs(cli): a .hyperframes folder in a subfolder is left out and not served

The private-file rule now treats a .hyperframes/ folder at any depth as the
app's records. Files stored in one inside a subfolder, assets included, stay out
of uploads and are not served by Studio, preview or render. The cloud render
section now says so beside the rule it already describes.

* fix(cli): capture pages keep loading scripts with no or unlisted extensions

With nosniff on every response, a script the capture page server did not
know the type of (a .cjs file, or a file with no extension) was served as
application/octet-stream, and the browser refused to run it.

The server now names .cjs, .wasm, .xml, source maps, web manifests, CSV,
WebVTT, glTF and more audio, video and image types. A file whose type is still
unlisted is served without nosniff, so the browser sniffs it as it did before
and such a script runs. Every listed type and every empty error response keeps
nosniff.

* fix(share): sync and share leave out a .hyperframes folder below the root

The .hyperframes rules in the source path policy matched only at the project
root, so a copy's records in a subfolder, such as
sub/.hyperframes/agent-runs.jsonl, fell through to the default rule and
travelled with share and sync.

A new nested-hyperframes-state rule leaves out a .hyperframes folder at any
depth below the root. It sits before the first allow rule, as the contract's
rule order requires. The root folder's Studio files and other portable files
travel as before. Stored snapshot reads skip the new rule through
stored_manifest.legacy_rule_regexes, the shape the server and Desktop copies
already use, so snapshots and bindings captured earlier still read.
2026-11-16 07:18:57 +00:00

4.1 KiB

Running the HyperFrames CLI

<SKILLS> is the folder that holds the loaded skill's folder. Every skill and reference writes the CLI as npx hyperframes (or bare hyperframes). Run each of those commands as:

node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" <command> <args...>

Run it in the user's project directory, never in the skills directory. npm starts in the home folder, so the project's package.json, node_modules and .npmrc cannot choose the CLI or the registry; the CLI then moves into the project and works there. This holds for every command, including the usage beacon, and for a project the person received from someone else. Do not run npx hyperframes in the project directly, and do not run a project's own scripts or wrappers in its place unless the person asks for that command by name.

For bundled Node helpers, use the same launcher with --script <absolute-script-path> <args...>. Helpers that call the CLI then run it through the launcher.

Standalone skill installs

Without a plugin manifest, the launcher runs the newest published CLI. The person installs and updates standalone skills with npx hyperframes skills update.

Plugin installs

Check the directory two levels above the loaded SKILL.md for plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json, or .cursor-plugin/plugin.json identifying hyperframes, or a Gemini extension manifest. That directory is <PLUGIN_ROOT>, and <SKILLS> is <PLUGIN_ROOT>/skills.

Call the directory you run the launcher in the working directory. It is a plugin install only when all three of these hold:

  • The name of <PLUGIN_ROOT> does not start with a dot, so it is not .agents or .claude.
  • <PLUGIN_ROOT> is not the working directory, and it does not contain it.
  • If <PLUGIN_ROOT> is inside the working directory, a folder whose name starts with a dot lies between them, as .claude does in ~/.claude/plugins/... when you work in ~.

Otherwise the skills are a standalone install, and the launcher ignores any manifest there. Ignore it too, and follow the standalone rules above. The launcher refuses a manifest that pins a release older than 0.9.34.

For a plugin installation, these rules also apply in every skill and reference:

  • Do not run hyperframes skills update, skills check, or npx skills add. The agent's plugin manager owns installation and updates. Read the skill at <PLUGIN_ROOT>/skills/<name>/SKILL.md; report a missing bundled skill instead of downloading a different release. Resolve all skill references inside this bundle, even if a standalone copy is also installed. Claude exposes the router as /hyperframes:hyperframes; other clients may expose /hyperframes.
  • The launcher selects the manifest's CLI version and disables automatic standalone skill installation, including during init. The first call may download that exact CLI version through npm. A download failure is an error, not permission to use latest. Existing project dependency files and lockfiles must not be overwritten to match the plugin; surface a runtime incompatibility before changing them.
  • For bundled Node helpers, the launcher also passes the release version to their dependency loader. External providers, registry downloads, and existing project dependencies have their own versions; a plugin version alone does not freeze those inputs.
  • Treat the plugin directory as read-only. Put outputs and temporary work in the project or a temporary directory. Pass this plugin root and launcher convention to any delegated agent so it does not fall back to global skills.

Newer skills come through the client's plugin update flow and a session reload, which the person runs. Do not update an installed plugin yourself.

The launcher suppresses CLI update notices as well as standalone skill refreshes, including when running an older CLI with a stale notice cache. It passes the release as HYPERFRAMES_PLUGIN_VERSION for plugin-aware helpers and as HYPERFRAMES_SKILL_PKG_VERSION for the existing helper-package bootstrap. Our release process versions those packages together.