* 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.
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.agentsor.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.claudedoes 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, ornpx 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.