BREAKING: `status`, `session_list`, `session_status`, `session_logs` and
`pointer_state` are no longer tools. They are `hhstream://…` resources. 26
tools became 21, and eight resources appeared beside them.
The reason is the split the protocol itself draws, which the first cut ignored.
A resource is **application**-controlled context: the host decides what to put
in front of the model, and "what is on this machine right now" is the host's
question. A tool is **model**-controlled: an act the model chooses to perform.
Nothing in those five verbs acts. So the line between the halves is *who
decides*, not what a call costs.
hhstream://status text, the units and the frame socket
hhstream://sessions {?all} the broker's own list object
hhstream://pointer the lease holder, buttons and keys
hhstream://containers every container, plus the orphans
hhstream://screen a frame, as an image blob
hhstream://sessions/{id} {?events}
hhstream://sessions/{id}/logs {?lines}
hhstream://outputs/{name} one output's frame, as a blob
What did *not* move is the interesting part. `shot` and `record` stay tools
though neither changes the desktop: capturing is an act at a moment, and an
agent in a loop has to be able to decide to look *now* -- in many clients a
resource is something a person attaches rather than something a model can
fetch. The same frames are readable as `hhstream://screen` and
`hhstream://outputs/{name}` as well, for a host that wants one in context
itself. `session_container` stays a tool for a harder reason: with an id the
CLI runs `container.reconcile`, which writes the record back, so it is not a
read at all. Only the no-id listing is a resource. **A resource read must never
write**, and `resources.py` says so where it would be tempting.
Three consequences worth naming:
* A refusal cannot be content. `ReadResourceResult` has no `isError`, so a CLI
refusal is raised as `-32602` with the same remedy text in `message` and the
same `{ok, exit_code, error, reason, hint, remedy}` in `data`. Returning the
broker's failure object as the *body* would make "no such session" read as a
successful read of a session.
* Arguments become query parameters, and only declared ones are accepted -- for
the reason every tool schema sets `additionalProperties: false`. A parameter
silently ignored is a read that answered a different question.
* A v1 tool name is told where it went: `session_list` comes back with "It is a
RESOURCE now ... read hhstream://sessions instead". "No such tool" alone
reads as a broken server rather than a moved surface.
`--toolsets frames,sessions,pointer,keyboard` lands with it, because 21 flat
tools is the same problem one size smaller. There is **no grouping primitive in
MCP** -- `Tool` carries name, title, description, inputSchema, outputSchema,
icons, annotations, _meta and execution, and nowhere to put a family -- so the
only honest lever is which tools the *server* lists, chosen at launch. An
unknown name is argparse's exit 2, never a silently empty server, and a tool
outside the selection is unreachable rather than merely unlisted. Resources are
deliberately not filtered by it: they are the host's context, not the model's
budget.
`--list-resources` joins `--list-tools`; both are in the package's own
entry-point check, with `--toolsets` beside them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
hyprland-headless-stream-plugin
A Nix flake that runs a headless Hyprland session and publishes its frames on a persistent Unix socket, so any process that can open a socket can see the screen without owning a display.
Two parts:
- NixOS module —
services.hyprland-headless-stream: starts Hyprland with no physical monitor, and a small frame server beside it. - Package —
hhstream— the frame server (publishes frames) and its client (reads them). Pure Python standard library.
{
inputs.hhstream.url = "git+https://<host>/git/<owner>/hyprland-headless-stream-plugin.git";
# in your host config
imports = [ inputs.hhstream.nixosModules.default ];
services.hyprland-headless-stream = {
enable = true;
# Optional: the default is one 1280x720@30 rule with an empty name, which
# is Hyprland's wildcard and applies to whatever outputs the GPU has.
outputs = [ { width = 1920; height = 1080; refresh = 60; } ];
};
}
Then any consumer:
hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
The socket is a plain file descriptor: the server serves every client that connects, and keeps running when one disconnects.
Driving it from an agent: the MCP server
hhstream-mcp is the hhstream CLI as Model Context
Protocol tools, so an agent can look at this
desktop, put an application on it, and aim its one pointer and keyboard at that
application through typed tools instead of a shell. One tool per CLI verb,
twenty-six of them; the interface is frozen in docs/CONTRACT-mcp.md.
It is a thin wrapper and nothing more: every tool builds the argv list the CLI's own parser takes, runs the CLI's own handler, and maps what came back. The idle clock, the pointer lease, the allowlist and the exit-code table all stay where they were.
Install it with the module — off by default, because it is the surface through which a language model starts processes on this machine:
services.hyprland-headless-stream = {
enable = true;
sessions.enable = true; # the session, pointer and keyboard tools need the broker
mcp.enable = true; # puts `hhstream-mcp` on the system PATH
};
Then register it with a client. The transport is stdio — one process per client, spawned by the client, no port and no daemon — so the whole configuration is a command and an environment:
{
"mcpServers": {
"hhstream": {
"command": "hhstream-mcp",
"env": {
"HHSTREAM_SOCKET": "/run/hhstream/control.sock",
"HHSTREAM_FRAME_SOCKET": "/run/hypr-stream/stream.sock"
}
}
}
}
Both variables are the CLI's own and both are shown at their defaults, so they
can be left out unless this machine moved a socket. The account the client runs
as needs what the CLI needs: membership of the compositor's group (hhstream)
to read the frame socket, and of the broker's to reach the control socket. The
server cannot recover that for itself the way the CLI does — see
docs/CONTRACT-mcp.md §5 — so if shot reports it cannot read the socket, the
answer is "command": "sg", "args": ["hhstream", "-c", "hhstream-mcp"] or an
account in the group.
hhstream-mcp --list-tools prints the table and exits, which is the quickest
way to check an install. Nothing else about the server is configurable: it holds
no state, caches no lease, and the pointer lease is an explicit argument on
every gesture tool for exactly that reason.
| Document | What it is |
|---|---|
docs/CONTRACT.md |
the wire protocol and the module surface — the interface other people build against |
docs/CONTRACT-sessions.md |
the broker, the containers and the input lease |
docs/CONTRACT-mcp.md |
the MCP tools: their names, arguments and error mapping |
docs/ARCHITECTURE.md |
how the pieces fit: compositor, capture, server, client |
README.dev.md |
how to build, test and hack on it |
examples/README.md |
the demo that films the screen: agent-eyes-demo.py |
Status: work in progress — the module and the test suite are being built.