{"id":13470441,"url":"https://github.com/anko/hudkit","last_synced_at":"2026-02-17T06:01:41.668Z","repository":{"id":30726968,"uuid":"34283227","full_name":"anko/hudkit","owner":"anko","description":"transparent fullscreen on-top click-through WebKit web view, for making cool desktop HUDs","archived":false,"fork":false,"pushed_at":"2024-05-30T02:22:13.000Z","size":149,"stargazers_count":108,"open_issues_count":12,"forks_count":15,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-21T13:57:23.937Z","etag":null,"topics":["desktop","experimental","gtk","hud","javascript-api","overlay-window","webkit","x11"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anko.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-20T20:01:13.000Z","updated_at":"2025-04-17T03:13:21.000Z","dependencies_parsed_at":"2024-03-04T18:47:12.499Z","dependency_job_id":"e228b1d3-2271-4aaf-90a1-b570f3995d4b","html_url":"https://github.com/anko/hudkit","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/anko/hudkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anko%2Fhudkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anko%2Fhudkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anko%2Fhudkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anko%2Fhudkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anko","download_url":"https://codeload.github.com/anko/hudkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anko%2Fhudkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29535934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop","experimental","gtk","hud","javascript-api","overlay-window","webkit","x11"],"created_at":"2024-07-31T16:00:30.383Z","updated_at":"2026-02-17T06:01:41.642Z","avatar_url":"https://github.com/anko.png","language":"C","readme":"# Hudkit\u0026ensp;[![](https://img.shields.io/github/actions/workflow/status/anko/hudkit/ci.yml?style=flat-square)](https://github.com/anko/hudkit/actions/workflows/ci.yml) ![](https://img.shields.io/badge/coolness-maximum-brightgreen.svg?style=flat-square)\n\nTransparent click-through web browser overlay (\"[HUD][wiki-hud]\") over your\nwhole desktop, using [WebKit][webkit].\n\nIf you know web development, you can use Hudkit to make the _coolest statusbar\nin existence_, or _SVG desktop fireworks_, or whatever else you can think of\nusing a fullscreen transparent web view for.\n\n## Features\n\n - Works with multiple monitors, and connecting/disconnecting them.\n - Has a [JavaScript API](#javascript-api), so scripts on the page can query\n   monitor layout and change which areas of the overlay are clickable, for\n   example.\n - Small executable.  Uses native GTK and WebKit libraries.\n - Supports modern web APIs like WebSockets, WebAudio, WebGL, etc.\n\nPlatforms: \u0026emsp;✔️ Linux (X11)\u0026emsp;✔️❔ [Linux (Wayland)](https://github.com/anko/hudkit/issues/20) \u0026emsp;🚫 [~~Windows~~](https://github.com/anko/hudkit/issues/19) \u0026emsp;🚫 [~~OS X~~](https://github.com/progrium/topframe)\n\n## Quick start\n\n```sh\ncd /tmp\ngit clone https://github.com/anko/hudkit.git\ncd hudkit\nmake\n./example/run.sh\n```\n\nIf `make` complains, check [dependencies](#dependencies).\n\nYou should see something like this, if you have 2 monitors:\n\n![hudkit example running on 2 monitors](https://user-images.githubusercontent.com/5231746/132109661-34cde61f-f1bf-49d1-ac0a-02af9993e94e.png)\n\nThe code for what you see there is in the [`example/` directory](example/).  It\ncontains some explanatory comments, so it might make a good starting point for\nyour experiments.  If you come up with a (fairly compact) example of your own,\nplease PR.\n\nTo open Web Inspector targeting the example page, `./example/run.sh --inspect`.\n\n## Usage\n\n```\nUSAGE: ./hudkit \u003cURL\u003e [--help] [--webkit-settings option1=value1,...]\n\n    \u003cURL\u003e\n        Universal Resource Locator to be loaded on the overlay web view.\n        For example, to load a local file, you'd pass something like:\n\n            file:///home/mary/test.html\n\n        or to load from a local web server at port 4000:\n\n            http://localhost:4000\n\n    --inspect\n        Open the Web Inspector (dev tools) on start.\n\n    --webkit-settings \u003csettings\u003e\n        The \u003csettings\u003e should be a comma-separated list of settings.\n\n        Boolean settings can look like\n            option-name\n            option-name=TRUE\n            option-name=FALSE\n\n        String, integer, and enum options look like\n            option-name=foo\n            option-name=42\n\n        To see settings available on your system's WebKit version, their\n        valid values, and default values, pass '--webkit-settings help'.\n\n        To see explanations of the settings, see\n        https://webkitgtk.org/reference/webkit2gtk/stable/WebKitSettings.html\n\n    --help\n        Print this help text, then exit.\n\n    All of the standard GTK debug options and env variables are also\n    supported.  You probably won't need them, but you can find a list here:\n    https://developer.gnome.org/gtk3/stable/gtk-running.html\n```\n\n## JavaScript API\n\nJavaScript on the web page context has a `Hudkit` object, with these properties:\n\n### `async Hudkit.getMonitorLayout()`\n\nReturn: an Array of `{name, x, y, width, height}` objects, representing your\nmonitors' device names and dimensions.\n\nExample:\n\n```js\nconst monitors = await Hudkit.getMonitorLayout()\n\nmonitors.forEach((m) =\u003e {\n  console.log(`${m.name} pos:${m.x},${m.y} size:${m.width},${m.height}`)\n})\n```\n\n### `Hudkit.on(eventName, listener)`\n\nRegisters the given `listener` function to be called on events by the string\nname `eventName`.\n\nCurrently listenable events:\n\n - `monitors-changed`: fired when a monitor is logically connected or\n   disconnected, such as through `xrandr`.\n\n   No arguments are passed to the `listener`.  Call `Hudkit.getMonitorLayout`\n   to get the updated layout.\n\n - `composited-changed`: fired when the ability of your desktop environment to\n   render transparency changes; typically when your compositor is killed or\n   restarted.\n\n   The main reason this exists is so if you accidentally kill your compositor,\n   you won't be stuck with the now fully opaque overlay window blocking your\n   whole desktop, as long as your page listens for this event and calls\n   `window.close()` in response.\n\n   Arguments passed to listener:\n\n   - `haveTransparency` (Boolean).  True if compositing is now supported, false\n     otherwise.\n\n### `Hudkit.off(eventName, listener)`\n\nDe-registers the given `listener` from the given `eventName`, so it will no\nlonger be called.\n\n### `async Hudkit.setClickableAreas(rectangles)`\n\nSets which areas of the overlay window are clickable.  By default, it is not\nclickable.  The given area replaces the previous.\n\nParameters:\n\n - `rectangles`: Array of objects with properties `x`, `y`, `width`, and\n   `height`.  Other properties are ignored, and missing properties are treated\n   as 0.  Can be an empty Array, to make everything non-clickable.\n\n   The area of the desktop represented by the union of the given rectangles\n   become input-opaque (able to receive mouse events).  All other areas become\n   input-transparent.\n\nReturn:  `undefined`\n\nExample:\n\n```js\n// Make a tall narrow strip of the overlay window clickable, in the top left\n// corner of the screen. The dimensions are in pixels.\nHudkit.setClickableAreas([\n  { x: 0, y: 0, width: 200, height: 1000 }\n], err =\u003e console.error(err))\n```\n\nNotes:\n\n - If the Web Inspector is attached to the overlay window, the area it occupies\n   is automatically kept clickable, independently of calls to this function.\n\n - When monitors are connected or disconnected, your clickable areas are reset\n   to nothing being clickable, because their positioning would be\n   unpredictable.  Subscribe to the `'monitors-changed'` event\n   (`Hudkit.on('monitors-changed', () =\u003e { ... })`) and update your clickable\n   areas accordingly!\n\n### `async Hudkit.showInspector([attached])`\n\nOpens the Web Inspector (also known as Developer Tools), for debugging the page\nloaded in the web view.\n\nParameters:\n\n - `attached`: Boolean.  If `true`, starts the inspector attached to the\n   overlay window.  If `false`, start the inspector in its own window.\n   (Optional.  Default: `false`.)\n\nReturn:  `undefined`\n\n:information\\_source: You can also start the inspector with the `--inspect`\nflag.  That's usually better, because it works even if your JS crashes before\ncalling this function.\n\n### Other Web APIs that work specially\n\n - [`window.close`](https://developer.mozilla.org/en-US/docs/Web/API/Window/close)\n   exits Hudkit.\n\n## Install\n\nIn the root directory of this project,\n\n    make\n\nIf you're missing any dependencies, the error should tell you which.\n\n### Dependencies\n\nYou'll need—\n\n- Standard *C compilation tools*: `make`, `pkg-config`, and any C compiler of\n  your choice (`gcc` or `clang`, probably).\n\n  Any Linux distro has these; many have them installed by default.  If not,\n  consult your distro's documentation on how to install them.  (Many distros\n  have a single package containing all the C tools, for convenience, like\n  [Arch][arch]'s [`base-devel`\n  package](https://archlinux.org/groups/x86_64/base-devel/).)\n\n- *GTK 3*, and a corresponding *webkit2gtk*.\n\n  On [Arch][arch], the packages are called `gtk3` and `webkit2gtk`.\n\n  On [Void][void], they are `gtk+3-devel` and `webkit2gtk-devel`.\n\n  On [Ubuntu][ubuntu], they are `libgtk-3-dev` and `libwebkit2gtk-4.0-devel`.\n\n  On [Mint][mint], they are `libgtk-3-dev` and `libwebkit2gtk-4.0`.\n\n  If you build on another distro, I'm interested in how it went.\n\n## Bugs\n\nProbably.  [Report them][new-issue].\n\n## FAQ\n\n\u003e Is it safe to direct Hudkit at some random untrusted web page on the\n\u003e internet?\n\nNo.  Hudkit is built on a web browser engine, but is not intended for use as a\ngeneral-purpose web browser.  The `window.Hudkit` object and other background\nstuff are exposed to every page Hudkit loads.  Although I've tried my best to\nmitigate possible attacks, the API simply is not designed to be exposed to the\nfull badness of the wider internet.\n\nPlease point Hudkit only at a locally hosted web pages, unless you really know\nwhat you're doing.\n\n\u003e How can I ensure my HUD doesn't accidentally load remote resources?\n\nDefine a\n[Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)\n(CSP), like you'd do when developing any other web page.  Hudkit supports those\nthrough WebKit.\n\nI recommend the following: Add this meta tag inside your document's `\u003chead\u003e`:\n\n```html\n\u003cmeta http-equiv=\"Content-Security-Policy\" content=\"default-src 'self' 'unsafe-inline'\"\u003e\n```\n\nThis makes that page only able to load resources from the same host it was\nloaded from (your local computer).  All requests to anywhere else are blocked.\nThe `'unsafe-inline'` part allows inline `\u003cscript\u003e` and `\u003cstyle\u003e` tags, which\nare innocuous if you're never loading remote resources anyway.\n\nYou can test this by e.g. adding a `\u003cimg src=\"http://example.com/\"\u003e` tag to\nyour page.  You'll see a log entry like this when it gets blocked:\n\n```\nCONSOLE SECURITY ERROR Refused to load http://example.com/ because it appears\nin neither the img-src directive nor the default-src directive of the Content\nSecurity Policy.\n```\n\nFor further documentation on CSP, consult [MDN Web\nDocs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)\nor [content-security-policy.com](https://content-security-policy.com/).\n\n\u003e Hudkit says my screen doesn't support transparency.  What does this mean?\n\nYou're probably running a plain window manager (like i3, XMonad, or awesomewm),\nwhich doesn't have a [built-in\ncompositor](https://en.wikipedia.org/wiki/Compositing_window_manager).  So\nyou'll need to install and run a standalone compositor.  I recommend\n[compton][compton], or [picom][picom].\n\n\u003e I can't type anything into the Web Inspector while it's attached to the\n\u003e overlay window!\n\nYep, it's a known problem.  You can work around it by detaching the web\ninspector into its own window, with one of the buttons in the top-left corner.\nIt works normally when detached.\n\nThis bug is hard to fix for complex technical reasons:  In short, we have to\nset X11's *override-redirect* flag on the overlay window, to guarantee that\nwindow managers cannot reposition it, reparent it, or otherwise mess with it.\nA side-effect of doing this is that the window does cannot receive input focus,\nwhich is fine for mouse events (since they aren't dependent on input focus),\nbut it means no keyboard events.  Unless you grab the keyboard device, which\nhas its own problems.\n\n\u003e My currently running Hudkit instance's page is in a weird state that I want\n\u003e to debug, but I forgot to pass the `--inspect` flag, and restarting it would\n\u003e lose its current state.  What do?\n\nYou can send the Hudkit process a `SIGUSR1` signal to open the Web Inspector.\nFor example, `killall hudkit --signal SIGUSR1`.\n\n\u003e Why am I getting a `SyntaxError` when I try to `await` a Hudkit function?\n\nProbably because you're trying to use `await` at the top-level of your\nJavaScript file.  This wart in the JavaScript standard is unfortunate, and the\nwording of WebKit's error message for it even more so.\n\nThe fix is to create an async function at the top-level, and immediately call\nit, doing all of your async stuff inside it:\n\n```js\n(async function () {\n  // You can use `await` here\n})()\n```\n\nThis will improve in the near future:  There is a [TC39 proposal for top-level\nawait](https://github.com/tc39/proposal-top-level-await), which is [backed by\nWebKit developers](https://github.com/whatwg/html/pull/4352), and\n[implementation is in\nprogress](https://bugs.webkit.org/show_bug.cgi?id=202484).\n\n\u003e Why is Xvfb complaining about _extension \"GLX\" missing on display \":99\"_ if I\n\u003e run the automated test?\n\nProbably because you're running an Nvidia proprietary driver which are [kind of\ngarbage](https://www.youtube.com/watch?v=_36yNWw_07g).  The test starts a\nbackground instance of X11 so your desktop's settings don't interfere with it,\nbut inside that context OpenGL is randomly bricked on some versions of the\nproprietary NV driver, and on some versions it works.  The actual program\nshould work just fine either way though.  Try the `example/`.\n\n## Related programs\n\n- [Electron][electron].  I've heard it's possible to make Electron\n  click-through and fullscreen.  I have not gotten it to work, but maybe you\n  can?  Let me know if you do.\n\n  Possible starting point:  Start `electron` with `--enable-transparent-visuals\n  --disable-gpu`.  Call [`win.setIgnoreMouseEvents`][electron_ignoremouse], set\n  all the possible \"*please dear WM, do not touch this window*\"-flags, call the\n  [`screen` API](https://electronjs.org/docs/api/screen) for monitor\n  arrangements and position your window accordingly.  Sacrifice 55 paperclips\n  to Eris of Discordia, kneel and pray.\n\n## JS libraries that I think work well with Hudkit\n\n - [dnode][dnode] makes it possible to make remote procedure calls from JS in\n   the web page to JS on a web server.\n - [SockJS][sockjs] lets is a simple abstraction over WebSockets, for\n   transferring data otherwise.\n - [D3][d3] is a great data visualisation library.\n\n## Programs that I think work well with Hudkit\n\n - [`xkbcat`][xkbcat] can capture keystrokes everywhere in X11, for making a\n   keyboard visualiser for livestreaming, or for triggering eye candy.\n - `sxhkd` is a fairly minimal X11 keyboard shortcut daemon.  Can use it to run\n   arbitrary commands in response to key combinations, such as throwing data\n   into a named pipe read by a locally running web server that's in contact\n   with hudkit by WebSocket.\n - `mpv` with the `--input-ipc-server` flag can be queried for the currently\n   playing music track.  Various other music players can do this too if you\n   google around.\n - `sensors` can show hardware temperatures and fan data.\n\n## License\n\n[ISC](https://en.wikipedia.org/wiki/ISC_license).\n\n\n[arch]: https://www.archlinux.org/\n[compton]: https://github.com/chjj/compton\n[d3]: https://d3js.org/\n[dnode]: https://github.com/substack/dnode\n[electron]: https://electronjs.org/\n[electron_ignoremouse]: https://electronjs.org/docs/api/browser-window#winsetignoremouseeventsignore-options\n[mint]: https://linuxmint.com/\n[new-issue]: https://github.com/anko/hudkit/issues/new\n[picom]: https://github.com/yshui/picom\n[pscircle]: https://gitlab.com/mildlyparallel/pscircle\n[sockjs]: https://github.com/sockjs/sockjs-client\n[twitch]: https://www.twitch.tv/\n[ubuntu]: https://ubuntu.com/\n[void]: https://voidlinux.org/\n[webkit]: https://www.webkit.org/\n[wiki-hud]: http://en.wikipedia.org/wiki/Head-up_display\n[wk-settings]: https://webkitgtk.org/reference/webkit2gtk/stable/WebKitSettings.html\n[xkbcat]: https://github.com/anko/xkbcat\n","funding_links":[],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanko%2Fhudkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanko%2Fhudkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanko%2Fhudkit/lists"}