Files
hyprland-headless-stream-pl…/README.md
T
HermenixandClaude Opus 5 6a40c7e2e4 docs(mcp): freeze the tool surface, and record what the in-process seam costs
`docs/CONTRACT-mcp.md` (mcp-v1) is the new interface, written the way this
repository writes interfaces: the tool names, the arguments each takes, the
flag form, what is deliberately absent and why, and a row per exit code saying
what it arrives as and what an agent should do about it. An agent that has
learned these names is a consumer like any other, so renaming one needs a
version bump.

README.md gains the section an operator reads: the `mcp.enable` option, the
`mcpServers` block to register it with, why both environment variables are
shown at their defaults, and what to do when `shot` cannot read the frame
socket. README.dev.md gains the `nix build .#hhstream-mcp` half of the build
section, the `vm-mcp` row, the new files in the layout, and the reason `mcp` is
in the unit check's environment. ARCHITECTURE.md gains the sixth box, drawn
above the CLI rather than beside the broker, because that is where it sits.

`docs/TODO/mcp-in-process-has-no-call-deadline.md` records the two things the
in-process seam costs, rather than leaving them to be rediscovered. A thread
cannot be interrupted, so there is no per-call deadline and a wedged call
queues every later one behind it; and `cli.main`'s `sg` re-exec is an `exec`
this server cannot perform, so a frame verb that cannot read the socket fails
where the CLI would have recovered. The second is the one an operator meets
first -- the CLI works from their shell and the tool does not -- which is why
the failure says what the CLI would have done and how to not need it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:33:07 +00:00

103 lines
4.0 KiB
Markdown

# 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.
```nix
{
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:
```bash
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](https://modelcontextprotocol.io) 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:
```nix
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:
```json
{
"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.