{"id":15282002,"url":"https://github.com/johnae/persway","last_synced_at":"2025-04-07T12:07:23.532Z","repository":{"id":45430955,"uuid":"183439843","full_name":"johnae/persway","owner":"johnae","description":"Petite Puppeteer of Pandemonium - your very own Sway IPC Imp","archived":false,"fork":false,"pushed_at":"2024-01-22T11:36:07.000Z","size":300,"stargazers_count":111,"open_issues_count":13,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-25T02:50:55.884Z","etag":null,"topics":["ipc","nix","rust-lang","swaywm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnae.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":null,"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":"2019-04-25T13:27:09.000Z","updated_at":"2024-04-24T07:36:07.000Z","dependencies_parsed_at":"2024-08-29T14:37:33.242Z","dependency_job_id":null,"html_url":"https://github.com/johnae/persway","commit_stats":{"total_commits":106,"total_committers":4,"mean_commits":26.5,"dds":0.2264150943396226,"last_synced_commit":"0fbc175a75d9191f9e5d717d8c80088d9d16ba58"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnae%2Fpersway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnae%2Fpersway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnae%2Fpersway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnae%2Fpersway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnae","download_url":"https://codeload.github.com/johnae/persway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648977,"owners_count":20972945,"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":["ipc","nix","rust-lang","swaywm"],"created_at":"2024-09-30T14:05:06.396Z","updated_at":"2025-04-07T12:07:23.508Z","avatar_url":"https://github.com/johnae.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\nhttps://user-images.githubusercontent.com/28332/223278211-ba3943ee-becc-45e5-ae0e-4f1a121a6f17.mp4\n\n_Parental Advisory - Explicit Content. Unmute the video for the full experience._\n\n## Persway - the scheming, evil sway ipc daemon\n\nPersway works with the Sway Compositor, it persuades it to do little evil things. It features window focus handlers that can be used to adjust the opacity of focused and non-focused windows among many other things. Persway currently supports two layouts: `spiral` and `stack_main`. The first alternates between horizontal and vertical splits based on window geometry - this usually results in something that looks like a spiral, this layout is the same as what persway previously just called `autolayout`. The latter, i.e `stack_main`, keeps a stack of windows on the side of a larger main area (this layout is sometimes referred to as master stack).\nPersway comes with several commands to control the `stack_main` layout as you move around in it. Persway talks to itself through a socket and listens to sway events through the sway socket making it a flexible tool for manipulating the [Sway Compositor](https://github.com/swaywm/sway).\n\nIn persway version 0.6.0 the cli interface was changed in a backwards incompatible way. However, the change is minor, all the options and arguments from previous versions are now instead available underneath the `daemon` subcommand. So the migration path is simply:\n\nIf your previous pre-0.6.0 setup looked like this:\n```\npersway -w -e '[tiling] opacity 1' -f '[tiling] opacity 0.95; opacity 1' -l 'mark --add _prev' --autolayout \n```\n\nThe same setup on 0.6.0 and up should instead look like this:\n\n```\npersway daemon -w -e '[tiling] opacity 1' -f '[tiling] opacity 0.95; opacity 1' -l 'mark --add _prev' --default-layout spiral\n```\n\nThis change was made because persway, as noted above, has gained the ability to talk to itself. That is - in version 0.6.0, persway can talk to itself through a socket to do various things.\n\n\n### Configure and setup Persway\n\nTo set up Persway, you need to run the daemon using the `persway daemon` subcommand with the appropriate options. Once the daemon is running, you can use the client portion of Persway to communicate with the daemon. For example by binding keys to layout movement and switching.\n\nIn essence, to set up Persway, follow these steps:\n\nRun the daemon using the appropriate options. Here's an example:\n\n```\npersway daemon -w -e '[tiling] opacity 1' -f '[tiling] opacity 0.95; opacity 1' -l 'mark --add _prev' -d stack_main\n```\n\nThen bind keys to layout movement and switching. For example, you could use the following sway bindings:\n\n```\nbindsym Mod4+Control+space exec persway stack-main-rotate-next\nbindsym Mod4+Shift+Tab exec persway stack-focus-prev\nbindsym Mod4+Tab exec persway stack-focus-next\nbindsym Mod4+c exec persway change-layout stack-main --size 70 --stack-layout tiled\nbindsym Mod4+space exec persway stack-swap-main\nbindsym Mod4+v exec persway change-layout manual\nbindsym Mod4+x exec persway change-layout stack-main --size 70\nbindsym Mod4+z exec persway change-layout spiral\n```\n\n### The cli\n\nThis is the main cli interface:\n\n```\nI am Persway. An evil, scheming, friendly daemon.\n\nI talk to the Sway Compositor and persuade it to do little evil things. Give me an option and see what it brings. I also talk to myself.\n\nUsage: persway [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  daemon\n          Starts the persway daemon\n  stack-focus-next\n          Applies to stack main layout - focuses the next stacked window\n  stack-focus-prev\n          Applies to stack main layout - focuses the previous stacked window\n  stack-swap-main\n          Applies to stack main layout - swaps the current stacked window with the main window\n  stack-main-rotate-next\n          Applies to stack main layout - pops the top of the stack into main while pushing the old main window to the bottom of the stack\n  change-layout\n          Changes the layout of the focused workspace\n  help\n          Print this message or the help of the given subcommand(s)\n\nOptions:\n  -s, --socket-path \u003cSOCKET_PATH\u003e\n          Path to control socket. This option applies both to daemon and client. Defaults to \u003cXDG_RUNTIME_DIR\u003e/persway-\u003cWAYLAND_DISPLAY\u003e.sock\n\n  -h, --help\n          Print help (see a summary with '-h')\n\n  -V, --version\n          Print version\n```\n\nThe daemon cli interface:\n\n```\nStarts the persway daemon\n\nUsage: persway daemon [OPTIONS]\n\nOptions:\n  -d, --default-layout \u003cDEFAULT_LAYOUT\u003e\n          Which layout should be the default when no other layout has been specified for a workspace. Options are: manual, spiral and stack_main\n          \n          [default: manual]\n\n  -w, --workspace-renaming\n          Enable automatic workspace renaming based on what is running in the workspace (eg. application name)\n\n  -f, --on-window-focus \u003cON_WINDOW_FOCUS\u003e\n          Called when window comes into focus. To automatically set the opacity of all other windows to 0.8 for example, you would set this to:\n          \n          [tiling] opacity 0.8; opacity 1\n          \n          Eg. set all tiling windows to opacity 0.8 but set the currently focused window to opacity 1. Or if you want to skip some applications - in this case firefox - you would do something like:\n          \n          [tiling] opacity 0.8; [app_id=\"firefox\"] opacity 1; opacity 1\n\n  -l, --on-window-focus-leave \u003cON_WINDOW_FOCUS_LEAVE\u003e\n          Called when window leaves focus. To automatically mark these for example, you would set this to:\n          \n          mark --add _prev\n          \n          and then in your sway config:\n          \n          bindsym Mod1+tab [con_mark=_prev] focus\n\n  -e, --on-exit \u003cON_EXIT\u003e\n          Called when persway exits. This can be used to reset any opacity changes or other settings when persway exits. For example, if changing the opacity on window focus, you would probably want to reset that on exit like this:\n          \n          [tiling] opacity 1\n          \n          Eg. set all tiling windows to opacity 1\n\n  -h, --help\n          Print help (see a summary with '-h')\n```\n\nThe `change-layout` subcommand takes layout subcommands:\n\n```\nChanges the layout of the focused workspace\n\nUsage: persway change-layout \u003cCOMMAND\u003e\n\nCommands:\n  spiral      The spiral autotiling layout tiles windows in a spiral formation, similar to AwesomeWM\n  stack-main  The stack_main autotiling layout keeps a stack of windows on the side of a larger main area, this layout comes with a few commands to control it as well\n  manual      The normal sway manual tiling\n  help        Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help  Print help\n```\n\nThe `change-layout` `stack-main` subcommand takes a few options:\n\n```\nThe stack_main autotiling layout keeps a stack of windows on the side of a larger main area, this layout comes with a few commands to control it as well\n\nUsage: persway change-layout stack-main [OPTIONS]\n\nOptions:\n  -s, --size \u003cSIZE\u003e                  Size of the main area in percent [default: 70]\n  -l, --stack-layout \u003cSTACK_LAYOUT\u003e  The sway layout of the stack: tabbed, tiled or stacked [default: stacked]\n  -h, --help                         Print help\n\n```\n\nThere are other subcommands as well. Go explore. I'll try to do a better job documenting things in the future.\n\nIf you have trouble with workspace naming/numbering and switching workspaces, please see this issue comment: https://github.com/johnae/persway/issues/2#issuecomment-644343784 - the gist of it is that it is likely a sway config issue.\n\n\n### Nix flake\n\nIf you happen to be on [NixOS](https://nixos.org) or you're using the Nix Package Manager, you can easily use the flake and overlay from this repo (provided you're using Nix flakes ofc).\n\nPersway is released under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnae%2Fpersway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnae%2Fpersway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnae%2Fpersway/lists"}