{"id":13436670,"url":"https://github.com/project-repo/cagebreak","last_synced_at":"2026-02-22T10:36:12.641Z","repository":{"id":50525199,"uuid":"241194950","full_name":"project-repo/cagebreak","owner":"project-repo","description":"Cagebreak: A Wayland Tiling Compositor Inspired by Ratpoison","archived":false,"fork":false,"pushed_at":"2024-08-12T14:17:16.000Z","size":1156,"stargazers_count":267,"open_issues_count":11,"forks_count":20,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-08-13T10:50:33.376Z","etag":null,"topics":["cage","compositor","ratpoison","tiling-window-manager","wayland","wlroots"],"latest_commit_sha":null,"homepage":"","language":"C","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/project-repo.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-17T19:54:25.000Z","updated_at":"2024-08-13T05:11:46.000Z","dependencies_parsed_at":"2023-12-09T14:23:28.772Z","dependency_job_id":"a54316f1-0667-48a9-9f2b-b690d55428ba","html_url":"https://github.com/project-repo/cagebreak","commit_stats":{"total_commits":38,"total_committers":6,"mean_commits":6.333333333333333,"dds":0.631578947368421,"last_synced_commit":"3d86ea36b69601da90d8c801c2329adfb36524c7"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-repo%2Fcagebreak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-repo%2Fcagebreak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-repo%2Fcagebreak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-repo%2Fcagebreak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/project-repo","download_url":"https://codeload.github.com/project-repo/cagebreak/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244310405,"owners_count":20432531,"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","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":["cage","compositor","ratpoison","tiling-window-manager","wayland","wlroots"],"created_at":"2024-07-31T03:00:51.139Z","updated_at":"2026-02-22T10:36:12.625Z","avatar_url":"https://github.com/project-repo.png","language":"C","funding_links":[],"categories":["C","Compositor","Compositors"],"sub_categories":["Tiling"],"readme":"# Cagebreak: A Tiling Wayland Compositor\n\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/6532/badge)](https://bestpractices.coreinfrastructure.org/projects/6532) [![Packaging status](https://repology.org/badge/tiny-repos/cagebreak.svg)](https://repology.org/project/cagebreak/versions) [![AUR package](https://repology.org/badge/version-for-repo/aur/cagebreak.svg?minversion=3.1.0)](https://repology.org/project/cagebreak/versions)\n\n[![Contact](img/mail.svg)](SECURITY.md) [![Manuals](img/manuals.svg)](manuals.md) [![FAQ](img/faq.svg)](FAQ.md) [![CONTRIBUTING](img/contributing.svg)](CONTRIBUTING.md) [![ArchWiki](img/archwiki.svg)](https://wiki.archlinux.org/title/Cagebreak) [![AUR](img/aur.svg)](https://aur.archlinux.org/packages?O=0\u0026K=cagebreak)\n\n## Introduction\n\nCagebreak provides a [ratpoison](https://www.nongnu.org/ratpoison/)-inspired, [cage](https://github.com/Hjdskes/cage)-based, tiling [Wayland](https://wayland.freedesktop.org/) compositor.\n\n  * Bugs, Contact Information and New Features:\n    * [Open an issue](https://github.com/project-repo/cagebreak/issues/new).\n    * Write an e-mail (See [SECURITY.md](SECURITY.md)).\n    * The Roadmap below outlines our plans.\n  * Compatibility \u0026 Development Distribution:\n    * Cagebreak supports [Arch Linux](https://archlinux.org/) and uses the library\n      versions from extra and core at the time of release.\n      Most other setups work with a [bit of luck](https://repology.org/project/cagebreak/versions).\n  * Quick Installation (on ArchLinux, more [here (ArchWiki)](https://wiki.archlinux.org/title/Cagebreak)):\n    1. Use the [cagebreak PKGBUILD](https://aur.archlinux.org/packages/cagebreak).\n    2. Add an example config such as [config](examples/config) to `$USER/.config/cagebreak/config`\n    3. Execute cagebreak like any other binary.\n  * Documentation:\n    * [man pages](manuals.md)\n    * [README](README.md), [FAQ](FAQ.md) \u0026 [SECURITY.md](SECURITY.md)\n  * What's new?: [Changelog](Changelog.md)\n  * Uninstallation: `pacman -R cagebreak`\n  * Contributing:\n    * [Open an issue](https://github.com/project-repo/cagebreak/issues/new) and state your idea.\n      We will get back to you.\n    * Ask before you open a pull request. We might not accept your code and\n      it would be sad to waste the effort.\n    * Respect the [Code of Conduct](CODE_OF_CONDUCT.md) (To date, we've never\n      had to intervene. - Keep it that way!)\n  * Name: Cagebreak breaks the kiosk of [Cage](https://github.com/Hjdskes/cage) into tiles, hence the name.\n\n## Installation\n\nOn [Arch Linux](https://archlinux.org/), use the [AUR](https://aur.archlinux.org/) [PKGBUILDs](https://wiki.archlinux.org/title/PKGBUILD):\n\n  * Using [cagebreak](https://aur.archlinux.org/packages/cagebreak), Cagebreak is\n    built on the target system (since release 1.3.0)\n  * Using [cagebreak-bin](https://aur.archlinux.org/packages/cagebreak-bin),\n    pre-built binaries are extracted\n    to the target system (since release 1.3.2)\n\nSee [cagebreak-pkgbuild](https://github.com/project-repo/cagebreak-pkgbuild) for details.\n\nYou may check out other distros here:\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/cagebreak.svg)](https://repology.org/project/cagebreak/versions)\n\n### Obtaining Source Code\n\nThere are different ways to obtain cagebreak source:\n\n  * [git clone](https://github.com/project-repo/cagebreak) (for all releases)\n  * [download release asset tarballs](https://github.com/project-repo/cagebreak/releases) (starting at release 1.2.1)\n\n#### Verifying Source Code\n\nThere are ways to verify that you obtained the correct source (See `keys/`\nand [CONTRIBUTING](CONTRIBUTING.md)):\n\n  * signature for the tarball of release assets starting at release 1.2.1\n  * signed tags for releases in the git history\n\n## Building Cagebreak\n\nCagebreak uses the [meson](https://mesonbuild.com/) build system.\n\nCagebreak is developed against the latest tag of wlroots, so as not to constantly\nchase breaking changes.\n\nExecute the following commands to build Cagebreak:\n\n```\n$ meson setup build -Dxwayland=true -Dman-pages=true --buildtype=release\n$ ninja -C build\n```\n\n### Man Pages\n\nRemove `-Dman-pages=true` to disable man page generation.\n\nTo generate man pages, make sure that you have [scdoc](https://archlinux.org/packages/extra/x86_64/scdoc/) installed.\n\n### Release Build\n\nTo obtain a debug build, remove `--buildtype=release`.\n\nThe release build is reproducible under conditions outlined in [CONTRIBUTING](CONTRIBUTING.md).\n\n### Xwayland Support\n\nTo build Cagebreak without XWayland support, remove `-Dxwayland=true`.\n\nTo use XWayland make sure that your version of wlroots is compiled with\nXWayland support.\n\nYou'll need to have [XWayland](https://archlinux.org/packages/extra/x86_64/xorg-xwayland/) installed for XWayland support to work.\n\n## Running Cagebreak\n\n```\n$ ./build/cagebreak\n```\n\nIf you run Cagebreak within an existing X11 or Wayland session, it will\nopen in a virtual output as a window in your existing session.\n\nIf you run it in a TTY, it'll run with the KMS+DRM backend.\n\nNote that a configuration file is required. For more configuration options, see the [man pages](manuals.md).\n\nPlease see `example_scripts/` for a basis to customize from.\n\n### Usage Philosophy\n\nCagebreak was built to suit the needs of its creators. This outlines\nhow we intended some parts of cagebreak and might ease learning how to use cagebreak a\nlittle bit. Please note that this does not replace the [man pages](manuals.md) or the [FAQ](FAQ.md).\nAlso, this is not intended as a guide on how cagebreak must be used but\nas a source of inspiration and explanation for certain particularities.\n\n1. Cagebreak is keyboard-based. Everything regarding cagebreak can be done\n   through the keyboard and it is our view that it should be. This does not mean\n   that pointers, touchpads and such are not available for the few applications\n   that do require them.\n\n2. Cagebreak is a tiling compositor. Every view takes up as much screen space\n   as possible. We believe this is useful, as only very few programs are typically\n   necessary to complete a task. To manage multiple tasks concurrently, we use\n   workspaces.\n\n3. Each task deserves its own workspace. Any given task (the sort of thing you\n   might find in your calendar or on your todo list) probably requires very few\n   views and ideally, these take up as much of the screen as possible.\n\n\u003e Combining 2. and 3. might look like this in practice:\n\n\u003e  * Task 1: Edit introduction section for paper on X\n\u003e  * Task 2: Coordinate event with person Y\n\n\u003e  * split screen vertically\n\u003e  * open web browser or pdf viewer to read literature\n\u003e  * focus next\n\u003e  * open editor\n\u003e  * change to a different workspace\n\u003e  * split screen vertically\n\u003e  * open calendar application\n\u003e  * focus next\n\u003e  * open chat application\n\n\u003e Now each task has its own workspace and switching between tasks is possible\n\u003e by switching between workspaces.\n\n\u003e Note that, for example by using the socket, more advanced setups are\n\u003e possible. But the user is warned that excessive tweaking eats into the work\n\u003e to be done.\n\n4. Use keybindings and terminal emulators for the right purpose. Given the\n   philosophy outlined above you probably launch the same few programs very\n   often and others are very rarely used. We believe that commonly\n   used programs should have their own keybindings together with the most\n   important cagebreak commands. All the rarely used programs should be launched\n   from a terminal emulator as they probably require special flags, environment\n   variables and file paths anyway.\n\n\u003e In practice this means thinking about the applications and cagebreak commands\n\u003e you use and taking your keyboard layout into account when defining keybindings for\n\u003e your individual needs.\n\n5. Cagebreak can't do everything, but with scripting you can do most things.\n   Through the socket and with a bit of scripting, you can use the internal state\n   of cagebreak in combination with cagebreak commands and the full power of\n   a scripting language of your choice to do almost whatever you want.\n\n\u003e Example scripts can be found in the repository under `example_scripts/`.\n\n## Resilience\n\nTo become more resilient to outages of GitHub, we have created a [website](https://cagebreak.project-repo.co).\n\nIt is not possible to open issues on the website directly, use the mail contact\nif GitHub is down.\n\nThe following links may be useful:\n\n  * [Artefacts mirror](https://cagebreak.project-repo.co/release-artefacts.html)\n  * [PKGBUILD depending on the mirror](https://cagebreak.project-repo.co/cb-red-pkgb/PKGBUILD)\n  * [binary PKGBUILD depending on the mirror](https://cagebreak.project-repo.co/cb-red-bin-pkgb/PKGBUILD)\n  * [cagebreak repo mirror](https://cagebreak.project-repo.co/cagebreak.git)\n  * [cagebreak-bin repo mirror](https://cagebreak.project-repo.co/cagebreak-pkgbuild.git)\n\n## Roadmap\n\nCagebreak plans to do or keep doing the following things\nin the future:\n\n  * React to all issues.\n  * Add or modify features, which the authors find convenient or important.\n  * Improve the [OpenSSF Best Practices Badge Program](https://bestpractices.coreinfrastructure.org/en) level.\n\n## Governance\n\nCagebreak is managed by project-repo.\n\nConsider project-repo a single benevolent dictator for life that happens\nto occupy at least two brains.\n\nProject-repo is a pseudonym of at least two individuals acting\nas benevolent dictators for the project by the others mutual consent.\n\nThe individuals comprising project-repo are not otherwise associated\nby payment from any organisation or grant.\n\n### Governance Issues\n\nUse [SECURITY.md](SECURITY.md) to contact project-repo.\n\n### Roles\n\nThere are members of project-repo and those who are not.\n\nThere are no specific roles forced unto anyone.\n\n### Bus Factor\n\nThe current bus factor for Cagebreak is: 1\n\nThe Bus Factor is a measure of how many people have to be\nincapacitated for a project to be unable to continue.\n\nProject-repo could react to issues (even confidential\ne-mails) and fix easier issues if any one individual were\nincapacitated.\n\nHowever, not all aspects of the code or release engineering\nare fully resilient to the loss of any one individual.\n\nWe strive to increase the bus factor to at least 2 in all\naspects.\n\n## Accessibility\n\n  * We use text input/output to interact with the user whenever possible. For\n    example, sending text-based commands to the cagebreak sockets allows\n    one to change every configurable feature of cagebreak.\n  * Color is displayed but never a vital part to operating cagebreak.\n  * Text size can be increased and background color adjusted using text commands.\n  * There is no screen reader support per se but using a screen reader on socket output\n    would work and cagebreak does not preclude the use of a screen reader\n    for any software run with it.\n\n## Bugs\n\n[Open an issue](https://github.com/project-repo/cagebreak/issues/new) is you find something.\n\nSee [SECURITY.md](SECURITY.md) for other means of contacting the Cagebreak authors and security issues.\n\nFixed bugs are assigned a number and summarized in [Bugs.md](Bugs.md) for future reference.\n\n## Contributors\n\n  * Aisha Tammy\n    * [make man pages optional](https://github.com/project-repo/cagebreak/pull/4), released\n      in 1.6.0 with slight modifications\n  * Oliver Friedmann\n    * [Add output scaling](https://github.com/project-repo/cagebreak/pull/34), released\n      in 2.0.0 with slight modifications\n    * [Fix: calibration matrix](https://github.com/project-repo/cagebreak/pull/49),\n      released in 2.2.1 with slight modifications\n  * Tom Greig\n    * Fix bug in merge_output_configs in 2.1.2\n  * sodface\n    * Add a screenshot example script in 2.3.0\n  * Luca Kennedy (unsigned-enby)\n    * [Add option to configure the anchor position of messages](https://github.com/project-repo/cagebreak/pull/61) in 2.3.0\n\n## License\n\nCopyright (c) 2020-2024 The Cagebreak authors\nCopyright (c) 2018-2020 Jente Hidskes\nCopyright (c) 2019 The Sway authors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-repo%2Fcagebreak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproject-repo%2Fcagebreak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-repo%2Fcagebreak/lists"}