{"id":32406590,"url":"https://github.com/agustinmista/positron","last_synced_at":"2025-10-25T12:55:25.180Z","repository":{"id":160614081,"uuid":"600251603","full_name":"agustinmista/positron","owner":"agustinmista","description":"Effortlessly control your Home Assistant devices using keyboard shortcuts","archived":false,"fork":false,"pushed_at":"2024-06-11T19:29:55.000Z","size":1792,"stargazers_count":41,"open_issues_count":2,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-06-12T04:26:21.044Z","etag":null,"topics":["alpinejs","electron","homeassistant","shortcuts","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agustinmista.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-02-10T23:37:14.000Z","updated_at":"2024-06-11T19:29:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"1dc2c347-63fc-4978-b239-21a3fa62d387","html_url":"https://github.com/agustinmista/positron","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/agustinmista/positron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustinmista%2Fpositron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustinmista%2Fpositron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustinmista%2Fpositron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustinmista%2Fpositron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agustinmista","download_url":"https://codeload.github.com/agustinmista/positron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustinmista%2Fpositron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280958217,"owners_count":26420235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["alpinejs","electron","homeassistant","shortcuts","typescript"],"created_at":"2025-10-25T12:55:21.472Z","updated_at":"2025-10-25T12:55:25.164Z","avatar_url":"https://github.com/agustinmista.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv style=\"text-align: center\"\u003e\n  \u003cimg src=\"assets/icon.png\"  width=\"30%\" height=\"30%\"\u003e\n  \u003ch2\u003ePositron\u003c/h2\u003e\n  \u003ch3\u003eCreate keyboard shortcuts for Home Assistant actions\u003c/h3\u003e\n\u003c/div\u003e\n\nPositron lets you associate global system shortcuts to requests to a [Home\nAssistant](https://www.home-assistant.io/) server. You can use this to toggle\nlights, enable scenes, run scripts, read sensors, and pretty much anything Home\nAssistant supports!\n\n\n## Features\n\n* Multiplatform: available for Windows, macOS and Linux (both `deb` and `rpm`\n  packages).\n\n* Associate keyboard shortcuts to HTTP requests to a Home Assistant server endpoint.\n\n  + Shortcuts are handled directly by Electron, and you can define any\n    combination of keys supported by its [Accelerator\n    API](https://www.electronjs.org/docs/latest/api/accelerator).\n\n  + The supported endpoints are described in the Home Assistant [REST\n    API](https://developers.home-assistant.io/docs/api/rest) documentation.\n\n  + Send request data: some endpoints require JSON data to be sent in the\n    request body. Positron lets you add this data using key/value pairs.\n\n* Custom notification handlers: if your request returns some useful data, you\n  can write a custom response handler to get a system notification when the\n  shortcut is triggered. This can be used to, for instance, get the state of a\n  sensor or read events.\n\n  + To implement a custom notification handler, you simply need to provide an\n    anonymous function of type:\n\n    `{ ok: boolean, body: string } =\u003e string`\n\n    The `ok` field indicates if the request was successful, and `body` contains\n    the raw data that the Home Assistant server replied with or an error\n    message. The return value of this function should be the content of the body\n    of your custom notification. For instance, the default custom notification\n    handler is:\n\n    `res =\u003e res.ok ? 'Ok' : res.body`\n\n  + NOTE: This uses Electron's `vm` module to run your custom code. This\n    provides some isolation so you don't shoot yourself in the foot, but it has\n    been proven not to be a _secure_ isolation mechanism. Keep your handler\n    simple and, needless to say, don't run code you don't trust here.\n\n* Manually trigger the request and see the response. Useful for debugging custom\n  notification handlers.\n\n* Automatically minimizes itself to the system tray.\n\n* Automatically save your configuration after changes.\n\n* Dark/light mode switch.\n\n## Setup\n\nAfter you first launch this app, you can set up your Home Assistant server\ndetails under the `Settings` page. You'll need:\n\n* A Home Assistant server URL (HTTP/HTTPS, hostname, port)\n* A [long-lived access\n  token](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token)\n\n## Disclaimer for Wayland users\nPositron isn't a native Wayland app and as such it will run under XWayland.\n\nBy design XWayland applications can't see inputs (such as keyboard shortcuts) performed in native Wayland apps. This means that shortcuts you configured in Positron will only work in other XWayland applications. This isn't something we have any control over.\n\nPossible workarounds include:\n- running X instead of Wayland\n- configuring global shortcuts (e.g. in KDE you can define custom shortcuts, which will work in all applications. To do that open Settings and find shortcuts page, click `Add Command` and paste something like this:\n```\ncurl -X POST -H \"Authorization: Bearer \u003ctoken\u003e\" -H \"Content-Type: application/json\" -d '{\"entity_id\": \"\u003centity\u003e\"}' \u003curl\u003e:\u003cport\u003e/api/services/\u003cdomain\u003e/\u003cservice\u003e\n```\nMore  information about creating API requests can be found in [official docs](https://developers.home-assistant.io/docs/api/rest/)\n\n## Screenshots\n\n### Homepage\n\n\u003cdiv style=\"text-align: center\"\u003e\n  \u003cimg src=\"assets/home.png\" width=\"75%\" height=\"75%\"\u003e\n\u003c/div\u003e\n\n### Creating shortcuts\n\n\u003cdiv style=\"text-align: center\"\u003e\n  \u003cimg src=\"assets/shortcut.png\" width=\"75%\" height=\"75%\"\u003e\n\u003c/div\u003e\n\n### Custom notification handlers\n\n\u003cdiv style=\"text-align: center\"\u003e\n  \u003cimg src=\"assets/custom-notification.png\" width=\"75%\" height=\"75%\"\u003e\n\u003c/div\u003e\n\n### Custom notifications\n\n\u003cdiv style=\"text-align: center\"\u003e\n  \u003cimg src=\"assets/notification.png\" width=\"50%\" height=\"50%\"\u003e\n\u003c/div\u003e\n\n### Settings menu\n\n\u003cdiv style=\"text-align: center\"\u003e\n  \u003cimg src=\"assets/settings.png\" width=\"50%\" height=\"50%\"\u003e\n\u003c/div\u003e\n\n## Install\n\n### Precompiled releases\n\nThe easiest way to install this app is to grab one of the [precompiled\nreleases](https://github.com/agustinmista/positron/releases).\n\nNOTE: the release binaries are **not signed**, so you might see Windows and\nmacOS complaining about them. This is not going to change unless this app gets\nsome traction, since both Microsoft and Apple charge you a fair amount of real\nmoney to let you become a trusted developer.\n\n  * On Windows, if you see the `Windows protected your PC` popup, you can\n    continue by clicking on `More info` and then `Run anyway`.\n\n  * On macOS, you might need to [allow apps from unidentified\n    developers](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac).\n\n### Build from source\n\nYou can also build Positron by yourself. Assuming you have `git` and `npm`\ninstalled, this should get you far:\n\n```\ngit clone https://github.com/agustinmista/positron.git\ncd positron\nnpm install\nnpm start     # starts the app\nnpm run make  # packages a binary/installer\n```\n\nPlease report any issue you might encounter while building the app and I will\nupdate this file accordingly.\n\n## Contributing\n\nFeel free to [open an\nissue](https://github.com/agustinmista/positron/issues/new) if you find a bug or\nif you'd like to see a new feature implemented.\n\nPRs are welcomed too!\n\n## License\n\nMIT License\n\nCopyright (c) 2023 Agustín Mista\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagustinmista%2Fpositron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagustinmista%2Fpositron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagustinmista%2Fpositron/lists"}