slice/containers
A session was a process group, so every application landed on whichever workspace the compositor happened to show: one session's capture caught another's windows, and a pointer aimed at one could land in the other. This is the pure half of the fix. containers.py computes the argv lists that create a session's container (headless output, numbered workspace bound to it as default and persistent, an anchored window rule pinning the session's class there, then the mode) and the one that tears it down, plus the lowest-free allocator for the 1000+slot band and the quarantine backstop for windows that match no container. It runs nothing: no subprocess, no socket, no file, no clock, and no import of ipc.py, so every decision that can be tested without a compositor is asserted in a unit test. Validation is a control, not style: these strings reach a compositor that acts on them, and a rule body is comma-separated, so a session id outside [a-z0-9-], a class outside [A-Za-z0-9._+-], a non-positive or fractional size and a blank quarantine name all raise ValueError naming the value. Releasing a workspace the allocator never handed out raises rather than no-opping, because the quiet version hands the same workspace to two sessions minutes later. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QS2JvrgmvXmimKFcqqDVoa
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/hyprland-headless-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.
| Document | What it is |
|---|---|
docs/CONTRACT.md |
the wire protocol and the module surface — the interface other people build against |
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.
Languages
Python
81.7%
Nix
18.1%
Shell
0.2%