HermenixandClaude Opus 5 8c99518a62 feat(live): live.sock, both ends
The socket CONTRACT-sessions.md §3.5 freezes, implemented on both sides and by
nobody else: `hhstream_live.control` answers it, `hhstreamd.live` asks it.

`control.Control` is the four ops and nothing more -- attach, detach, list,
viewers -- with the decisions the daemon is allowed to make and no others. It
owns the two things only this process knows: how to build a capture for an
output (the capture command, from this unit's argv) and what a URL looks like
(the bound port). Both are injected as callables by `__main__.control_server`,
which is also why `attach` replies with a URL rather than letting the broker
assemble one from a port it was told about once.

`attach` is idempotent on the phrase and returns the existing stream, so a
re-`enable` after a broker restart cannot double the `grim` rate on an output.
The same phrase aimed at a *different* output is `invalid_argument`, because
that is a mistake and not a request.

Two details that are the point rather than polish:

* `_phrase_of` holds a caller's phrase to the generated shape and raises a
  shape-only message, with `from None`. `phrase.validate` names the value it
  rejected, which is correct for a library and wrong here: this value is a
  password, and the refusal travels back over a socket and into a log.
* `ControlServer.serve_forever` reads `self._sock` into a local before using
  it. `close()` runs on the main thread while this one is in `accept()`, and
  the attribute it was reading can be gone by the time it is dereferenced.

`hhstreamd.live` is the broker's client: one op at a time behind a lock, a
2-second timeout, `LiveUnavailable` for "could not be reached or did not answer
intelligibly" and `LiveRejected` carrying the `kind` the broker maps to an exit
code -- the pointer driver's client, verb for verb, because the broker already
knows how to hold one of those. `Attachment.parse` refuses a malformed reply
rather than defaulting its way past one.

`fps` is omitted from an `attach` unless a caller named one, which is what makes
`sessions.stream.fps` on the daemon's unit authoritative instead of decorative.
And `_safe()` renders a phrase as `<phrase:5 tokens>` for the one log line that
mentions a stream at all: the shape, never the words.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:47:16 +00:00
2026-10-11 22:47:16 +00:00
2026-10-09 11:32:42 -04:00
2026-09-28 05:01:41 +00:00
2026-09-28 05:01:41 +00:00

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://status is whether the desktop is up, hhstream://sessions is what is running, hhstream://sessions/<id>/logs is an application's own output, hhstream://pointer is who holds the input lease, hhstream://screen is a frame of the screen.
  • Tools are the acts — twenty-one, one per CLI verb that does something. session_start puts an application on the screen, pointer_acquire takes the input lease, keyboard_type types, session_kill ends 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.

S
Description
No description provided
Readme
2.8 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 81.7%
Nix 18.1%
Shell 0.2%