The broker half of sessions-v4: `stream.enable`, `stream.disable`, `stream.list`, `stream.status`, `start`'s three new arguments, and the one rule that is genuinely new rather than additive -- a connected viewer is activity. The decisions worth reading the diff for: **A stream never falls back to the main output.** `_stream_output` refuses when a session has no container, and the refusal is stronger than the pointer's for a reason the hint states: the main output carries *every other session*, so a fallback would put somebody else's desktop on a phone behind a phrase that was issued for this one. **The phrase lives in the record, so re-enabling returns the same URL.** A different `--phrase` on an already-enabled session is `stream_busy` (exit 8), not a silent rotation: rotating under a caller who is holding the old URL is the one outcome neither answer can be mistaken for. `disable` then `enable` is how it rotates, which is explicit. **`_checked_phrase` raises the shape and never the value**, with `from None`, for `control._phrase_of`'s reason: `phrase.validate` names what it rejected, and this value is a password on its way into an error reply and a log. **`fps` is only sent when a caller named one** (`_checked_fps` returns `None` otherwise), which is what makes the daemon's own default authoritative instead of decorative. The broker holds the daemon to the frozen cap before sending, so a nonsense rate is exit 2 from the verb rather than a surprise from the socket. **`attached` is its own field and is not folded into `enabled`.** A record can say the operator asked for a stream while the daemon is down, and those are two different facts; `url` and `viewers` are *absent* rather than stale when it is false, because a URL that no longer serves anything is worse than no URL. `stream.list` also reports `available`, so "no streams" is distinguishable from "no daemon" without parsing an error. **The viewer sweep** (`_sweep_streams`, every `STREAM_SWEEP_S = 60`s) asks the daemon for viewer counts and stamps `touch` on every session somebody is watching. It is the only thing in this daemon that treats an observation as an intention, and it exists for one failure: an operator watching a long job on his phone and losing the session at three hours *because* watching was all he was doing. It cannot hold a session open by itself -- an enabled stream with no viewer runs no `grim` and stamps nothing -- which is why it is safe to run unconditionally. **Teardown detaches before it destroys the container.** The other order makes every capture fail against a removed output, which is a stream that gives up ten frames later and a log that blames `grim`. `start` takes `stream`, `stream_phrase` and `stream_fps` and reports a stream it could not open in `stream_error` beside a session that *did* start, because the exit code is 0 and a caller who asked for a stream must not read that as one. Registry schema 3 -> 4: the record gains `stream`, older records migrate to `null` rather than being refused, and the viewer count is deliberately not stored -- a viewer count on disk is a number that is wrong the moment it is written. No new exit numbers: `stream_busy` -> 8, `stream_budget` -> 6, `stream_unavailable` -> 10. The last one is 10 for `driver_refused`'s reason -- the session keeps running, and a caller that read an unreachable stream as a dead session would kill an application over a web page. 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 behind a Model Context
Protocol surface, so an agent can look at this
desktop, put an application on it, and aim its one pointer and keyboard at that
application without writing command lines. The interface is frozen in
docs/CONTRACT-mcp.md.
It is split the way the protocol splits things:
- Resources are the state — eight of them, read by URI, and reading one
changes nothing.
hhstream://statusis whether the desktop is up,hhstream://sessionsis what is running,hhstream://sessions/<id>/logsis an application's own output,hhstream://pointeris who holds the input lease,hhstream://screenis a frame of the screen. - Tools are the acts — twenty-one, one per CLI verb that does something.
session_startputs an application on the screen,pointer_acquiretakes the input lease,keyboard_typetypes,session_killends a session.
A host decides what state to put in front of its model; the model decides what
to do. That is the whole of the split, and it is why shot is still a tool
(capturing is an act at a moment) while hhstream://screen exists beside it.
It is a thin wrapper and nothing more: every tool and every resource 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 and --list-resources print the two tables and
exit, which is the quickest way to check an install.
If twenty-one tools is more than a client has room for, --toolsets narrows
what is offered to whichever families are wanted — frames, sessions,
pointer, keyboard:
{ "command": "hhstream-mcp", "args": ["--toolsets", "frames,pointer,keyboard"] }
Resources are deliberately not narrowed by it: they are the host's context, not the model's tool budget. Nothing else about the server is configurable — it holds no state and 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 surface: the resource URIs, the tool names, their arguments and the 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.