{"id":24277272,"url":"https://github.com/zouloux/phoenix-space-grid","last_synced_at":"2025-03-05T10:47:31.121Z","repository":{"id":271900730,"uuid":"914921539","full_name":"zouloux/phoenix-space-grid","owner":"zouloux","description":"Phoenix script for mac Virtual Spaces","archived":false,"fork":false,"pushed_at":"2025-02-10T09:18:41.000Z","size":205,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-10T10:26:34.169Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/zouloux.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2025-01-10T15:28:52.000Z","updated_at":"2025-02-10T09:18:44.000Z","dependencies_parsed_at":"2025-02-10T10:24:08.688Z","dependency_job_id":"9340d9c7-515e-4663-ac19-c0893b1f011e","html_url":"https://github.com/zouloux/phoenix-space-grid","commit_stats":null,"previous_names":["zouloux/phoenix-space-grid"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zouloux%2Fphoenix-space-grid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zouloux%2Fphoenix-space-grid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zouloux%2Fphoenix-space-grid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zouloux%2Fphoenix-space-grid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zouloux","download_url":"https://codeload.github.com/zouloux/phoenix-space-grid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242014594,"owners_count":20057874,"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":[],"created_at":"2025-01-15T23:44:40.805Z","updated_at":"2025-03-05T10:47:31.115Z","avatar_url":"https://github.com/zouloux.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Phoenix Grid\n\nThis Phoenix script is a custom implementation of Virtual Spaces on mac.\nIt creates virtual spaces without using the natives ones of MacOS.\nThis allows us to have **instant space switch** with **zero transition**.\n\n#### Why\n- Native mac spaces are slow to switch, animation is too long\n- [Total-Space](https://totalspaces.binaryage.com/) is not supported anymore\n\n#### No caveat\n- **alt + tab** still works, it changes Virtual Spaces when switching app\n- **App Exposé** and **Mission Control** works as expected, it shows only the current Virtual Space apps\n- Fully configurable\n- Does not need **System Integrity Protection** to be disabled\n- Can be extended and customized by updating [phoenix-space-grid.js](phoenix-space-grid.js)\n\n#### Caveat\n- You have to config everything in a JS file, no UI to configure spaces.\n- Yet another tool to install\n\n#### What is needed\n- A Mac\n- Git\n- [Phoenix](https://github.com/kasper/phoenix/releases/) installed ( free )\n- [Better Touch Tool](https://folivora.ai/) installed ( not free )\n- Programming basics\n- 4 fingers\n\n\u003e This is very beta and default settings are my own. Tweak it for your needs!\n\n#### Usage\n- This will create a 1 dimensional virtual spaces list.\n- Each space will contain **top**, and **bottom** apps\n- Switch space with 4 fingers swipe left / right\n- Switch top app with 4 fingers swipe top\n- Switch bottom app with 4 fingers swipe bottom\n\n![screenshot-1.png](screenshot-1.png)\n\n\u003e This is not a real 2D grid on purpose, switching between apps is quicker like so\n\n\u003e Works well with 2 screens vertical setup with the external monitor optional\n\n#### Todo\n- [ ] Add a loading state that locks events and prints only a \"loading\" Modal\n- [ ] Add config to place grid anywhere ( corner anchor, then screen selection later )\n- [ ] Better UI ( Tied to Phoenix ? )\n- [ ] Bypass Better Touch Tool dependency ( Tied to Phoenix ? )\n- [ ] 4 fingers swipes still triggers 2 fingers swipes in some cases, needs to be patched\n- [x] Test with multiple screens setup\n- [x] Do not show grid when switching from an omni app\n- [x] Better code documentation\n- [x] Grid configuration\n\n---\n## Setup\n\n#### Install Phoenix\n- [Download and install Phoenix](https://github.com/kasper/phoenix/releases/)\n- [Download and install Better Touch Tool](https://folivora.ai/)\n\n#### Install Phoenix Space Grid script\nRun this command to download and install **phoenix-space-grid** with default config.\n- This will **override** `~/.phoenix.js` file.\n- Will be installed in `~/phoenix-space-grid`\n\n```bash\ngit clone git@github.com:zouloux/phoenix-space-grid.git ~/phoenix-space-grid\ncd ~/phoenix-space-grid\ncp config.default.js config.js\nrm ~/.phoenix.js\ncp .phoenix.js ~/.phoenix.js\n```\n\n#### Better touch tool\nTo catch 4 finger swipes and forward them to Phoenix, install [those triggers](./exported_triggers.bttpreset).\n\n#### Config your mac\n- Disable all 4 fingers gestures in **System Settings \u003e Trackpad \u003e More gestures**\n- Remove all your native MacOS Spaces, this script will create Virtual Spaces. \n\n\n#### Edit config\nNow edit `~/phoenix-space-grid/config.js` and adapt to your needs, when finished, run `./restart-phoenix.sh`\nYou should receive a \"Phoenix reloaded\" notification.\n\nIn `config.js`, your application names has to be exactly correct ( case, spaces, etc ).\nTo see an application name, simply start it and use **command tab** to display it.\n\n\n\n\u003e Please note that the first update can be slow if you have a lot of apps running.\n\n#### Update\n\n```bash\ncd ~/phoenix-space-grid\ngit pull\n./restart-phoenix.sh\n```\n\n---\n## Dev\n\nIf you are brave enough to tweak this script.\n\n#### Logs\nWhen editing `~/phoenix-space-grid/phoenix-space-grid.js`\nTo check Phoenix logs, start `~/phoenix-space-grid/stream-logs.sh`.\nIt will only print outputs when using `log()` and `info()` functions.\n\n#### Refreshing\nIf you update config or script, Phoenix will try to restart. Sometimes it create multiple instances of Modals, memory leak, and will eventually crash.\nYou can setup [this Raycast script](./restart-phoenix.sh) to restart Phoenix fully when working on config or script.\n\n\u003e If you do not have Raycast, simply run this script to restart Phoenix \n\n#### Other trials\nI tried other workflow, see them in [old](./old).\n- 2D grid ( like Total Space ) -\u003e Too much time to go from a space to another, but worked well\n- Radial alt-tab -\u003e Very cool but never finished \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzouloux%2Fphoenix-space-grid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzouloux%2Fphoenix-space-grid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzouloux%2Fphoenix-space-grid/lists"}