{"id":50811782,"url":"https://github.com/grepsedawk/i3wm-osx","last_synced_at":"2026-06-13T05:06:27.745Z","repository":{"id":356341461,"uuid":"1232093340","full_name":"grepsedawk/i3wm-osx","owner":"grepsedawk","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-07T16:57:34.000Z","size":44,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T17:38:11.855Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","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/grepsedawk.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T15:25:19.000Z","updated_at":"2026-05-07T16:57:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/grepsedawk/i3wm-osx","commit_stats":null,"previous_names":["grepsedawk/i3wm-osx"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/grepsedawk/i3wm-osx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grepsedawk%2Fi3wm-osx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grepsedawk%2Fi3wm-osx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grepsedawk%2Fi3wm-osx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grepsedawk%2Fi3wm-osx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grepsedawk","download_url":"https://codeload.github.com/grepsedawk/i3wm-osx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grepsedawk%2Fi3wm-osx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34272694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"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":[],"created_at":"2026-06-13T05:06:26.949Z","updated_at":"2026-06-13T05:06:27.738Z","avatar_url":"https://github.com/grepsedawk.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i3wm-osx\n\nA tiling window manager for macOS that reads i3 config files and behaves like i3wm.\n\n## Install via Homebrew\n\n```bash\nbrew tap grepsedawk/tap\nbrew install i3wm-osx\n\nmkdir -p ~/.config/i3wm-osx\ncp \"$(brew --prefix)/etc/i3wm-osx/config.example\" ~/.config/i3wm-osx/config\n\nbrew services start i3wm-osx     # autostart on login\n# or one-shot:  open \"$(brew --prefix)/opt/i3wm-osx/i3wm-osx.app\"\n```\n\nThis installs a prebuilt, signed `.app` bundle at `$(brew --prefix)/opt/i3wm-osx/`.\nThe signing identity is stable across releases, so Accessibility / Input\nMonitoring grants survive `brew upgrade`. First launch needs those permissions\ngranted to the bundle — see [Permissions](#permissions).\n\n\u003e ⚠️ Apple Silicon only for now (`depends_on arch: :arm64`). Intel users\n\u003e need the [manual build](#manual-build).\n\u003e\n\u003e ⚠️ Gatekeeper will warn \"unidentified developer\" on first launch (the cert\n\u003e is self-signed, not from Apple). Right-click the bundle in Finder → Open,\n\u003e then click Open in the dialog. Subsequent launches go through silently.\n\n## Status\n\n**Early prototype.** Targets the [grepsedawk i3 config](https://github.com/grepsedawk/.dotfiles/blob/master/.i3/config) as its compatibility benchmark.\n\nWhat works:\n\n- Tree-based tiling (splith, splitv, tabbed, stacking) with i3 layout semantics\n- Numbered workspaces with `workspace_auto_back_and_forth`\n- Multi-monitor \"outputs\"\n- i3 config parser: `set $var`, `bindsym`, `exec[_always]`, `for_window`, `mode`, gaps, colors, `floating_modifier`, bar block\n- i3 command parser/executor for: `focus`, `move`, `split`, `layout`, `workspace`, `kill`, `exec`, `fullscreen`, `floating`, `gaps`, `mode`, `resize`, `reload`, `restart`, `exit`\n- Global hotkeys via `CGEventTap` (Mod4 → Command, Mod1 → Option)\n- i3 IPC over UNIX socket with `i3-msg` companion CLI (`RUN_COMMAND`, `GET_WORKSPACES`, `GET_OUTPUTS`, `GET_TREE`, `GET_VERSION`)\n- Status bar across the top of every monitor with workspace pills + status command output (Dracula theme)\n- Floating windows toggle, smart gaps, inner/outer gaps\n\nWhat doesn't work yet:\n\n- Scratchpad\n- Marks / `[con_mark=…]` criteria\n- Stacking layout titlebars are minimal\n- Window borders (we set `default_border none`, which matches the target config)\n- `move scratchpad`, `sticky`, `urgent` hint\n\n## Manual build\n\n```bash\n# 1. One-time: create a self-signed code-signing identity so macOS TCC\n#    remembers your Accessibility / Input Monitoring grant across rebuilds.\n#    Without this, every `swift build` changes the binary's cdhash and macOS\n#    re-prompts you to grant access. macOS will ask for your login keychain\n#    password during this step.\n./setup-signing.sh\n\n# 2. Build \u0026 package as a proper .app so TCC has a stable identity to grant.\n./build-app.sh                  # produces build/i3wm-osx.app\n\n# 3. Drop a config file (i3 syntax). This file is intentionally separate\n#    from ~/.i3/config — modifier defaults, available exec commands, and\n#    special keys differ on macOS.\nmkdir -p ~/.config/i3wm-osx\ncp examples/config-macos ~/.config/i3wm-osx/config\n```\n\n## Permissions\n\nOn first launch, macOS pops a dialog asking for **Accessibility** access — click \"Open System Settings\" and toggle i3wm-osx on. Then do the same for **Input Monitoring** (needed for global hotkeys). The daemon polls every 2s and re-bootstraps as soon as both are granted, so you don't need to restart it.\n\nIf you previously granted Accessibility to your terminal (Alacritty, iTerm, Terminal, etc.) by mistake, **remove that entry** — TCC won't auto-clean it, and a wrongly-granted terminal will make the prompt name *that* app every time you launch from a shell.\n\n## Running\n\n```bash\n# Brew install:\nopen \"$(brew --prefix)/opt/i3wm-osx/i3wm-osx.app\"\n\n# Manual build:\nopen build/i3wm-osx.app\n# or with stderr visible:\nbuild/i3wm-osx.app/Contents/MacOS/i3wm-osx\n```\n\nThe first thing the daemon prints to stderr is a diagnostic block telling you what's working:\n\n```\n[i3wm-osx] Accessibility trust: GRANTED\n[i3wm-osx] screens: 2 — Built-in Retina Display, Studio Display\n[i3wm-osx] scanned: 17 windows across 2 output(s)\n[i3wm-osx] hotkey tap: INSTALLED\n[i3wm-osx] bar windows: 2\n[i3wm-osx] IPC listening on /tmp/i3wm-osx-alex.sock\n```\n\nIf trust is DENIED and you grant it after launch, the daemon polls every 2 seconds and re-bootstraps automatically — you don't need to restart it.\n\n## Notes on the config\n\ni3 conventions are preserved as written:\n\n| i3 keyword       | macOS modifier (default)                      |\n|------------------|-----------------------------------------------|\n| `Mod4` / `super` | ⌥ Option (override via `I3WM_OSX_MOD4=command`) |\n| `Mod1`           | ⌥ Option (override via `I3WM_OSX_MOD1=command`) |\n| `cmd` / `command`| ⌘ Command                                     |\n| `option` / `alt` | ⌥ Option                                      |\n| `Control`        | ⌃ Control                                     |\n| `Shift`          | ⇧ Shift                                       |\n\nValid override values: `command`, `option`, `control`, `shift`. Set via env var when launching, e.g. `I3WM_OSX_MOD4=command open build/i3wm-osx.app`.\n\nLinux-only commands like `pactl`, `rofi`, `xmodmap` will simply fail to exec; replace them with macOS equivalents in your config (e.g. `osascript`, `choose`, etc.).\n\n## Scripts\n\n- `setup-signing.sh` — one-time. Mints a self-signed code-signing identity so the `.app` keeps a stable cdhash across rebuilds. Without it, every rebuild invalidates your TCC grants.\n- `build-app.sh` — main build path. Compiles via SwiftPM, assembles `build/i3wm-osx.app`, codesigns with the identity from `setup-signing.sh` (or ad-hoc with a warning).\n- `scripts/dev-run.sh` — dev convenience. `swift build -c release` + execs the bare binary against `~/.i3/config` (or the bundled example). Skips the `.app` bundle, so it does **not** get TCC permissions — useful only when iterating on code that doesn't need AX.\n- `scripts/macos-tune-animations.sh on|off` — disables (or restores) macOS-wide window/Dock animations so workspace switches feel like i3 on Linux. Affects every app, not just i3wm-osx.\n\n## Releases\n\n- `.github/workflows/release.yml` — on `v*` tag push, builds `.app` on macOS-14 (arm64), signs with the `i3wm-osx-ci` cert imported from `MACOS_CERT_BASE64` / `MACOS_CERT_PASSWORD` GH secrets, tarballs with the bundled config example, attaches to the GH release. The Homebrew formula at [grepsedawk/homebrew-tap](https://github.com/grepsedawk/homebrew-tap) installs that prebuilt artifact — same cdhash for every user, so TCC grants persist across `brew upgrade`.\n\n## Architecture\n\n- `App.swift` — top-level coordinator\n- `AX.swift` / `Window.swift` — Accessibility API wrappers\n- `Tree.swift` — i3-style container tree with layout computation\n- `WindowManager.swift` — observes new windows, places them in the tree, applies layouts\n- `Workspace.swift` — workspaces and outputs (monitors)\n- `Config.swift` — i3 config parser\n- `Commands.swift` — i3 command parser and executor\n- `Hotkey.swift` — CGEventTap-based global hotkey daemon\n- `IPC.swift` — i3 IPC server\n- `Bar.swift` — top-of-screen status bar\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrepsedawk%2Fi3wm-osx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrepsedawk%2Fi3wm-osx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrepsedawk%2Fi3wm-osx/lists"}