Skip to main content
An agent harness (Claude Code, Codex, your own) runs hyperframes commands on the agent’s behalf. HF_TOOL_CONTEXT lets the harness tell one invocation what it supports, so the CLI can do more for it: report the images it produced, or wait its turn instead of racing another command in the same project. Without the variable, every command behaves exactly as it does in a terminal.
The harness sets the variable for one tool call, reads what the call produced, and removes its files.

​
The declaration

The CLI ignores capability names it does not know, and a known capability whose value is invalid, so a harness can declare capabilities newer than the CLI it runs. The variable carries data only: no capability runs code the harness names.

​
events: what a command produced

The CLI appends one JSON object per line to path. It never creates the parent directory, and a write that fails prints a warning without failing the command. Read the file after the command exits; several commands in one shell call append to the same file. Each line is an event:
Paths are absolute and stay where the command saved them. What to do with an artifact is the harness’s decision: attach the contact sheet to the tool result, link the report, or ignore it. Ignore event types and roles you do not know; new ones are added without a version change.

​
project-lock: one browser command at a time

check and snapshot take a lock on the project before they start a browser, and release it when they finish. A second command waits up to waitMs milliseconds for the lock, then fails, naming the command and process that hold it. A lock whose process has exited is taken over. A project.lock.break left by a killed process is not: the timeout names that file and its process id, and says to delete it to continue. The lock is the file .hyperframes/project.lock. Choose waitMs below your tool call’s own timeout, so a wait ends in the CLI’s message rather than the harness killing the call.

​
Hooks that run code

Running your own command before or after a CLI command is not a HF_TOOL_CONTEXT capability and never will be: anything that sets an environment variable could then run code. Such hooks, when they exist, come only from configuration the person controls.

​
Conformance

packages/cli/src/utils/toolContext.test.ts and projectLock.test.ts pin the parsing, event and lock behavior above. A harness is correct when it sets the variable for each call it wants the behavior on, reads events only after the call exits, and works the same when the CLI ignores a capability.