{"id":50842603,"url":"https://github.com/mjun0812/chrome-vertical-tab-toggle-hammerspoon","last_synced_at":"2026-06-14T07:07:52.555Z","repository":{"id":364008194,"uuid":"1261675599","full_name":"mjun0812/chrome-vertical-tab-toggle-hammerspoon","owner":"mjun0812","description":"Hammerspoon script to toggle Chrome's native vertical tab sidebar via keyboard shortcut or left-edge mouse hover (macOS)","archived":false,"fork":false,"pushed_at":"2026-06-07T08:55:01.000Z","size":1975,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T09:31:47.700Z","etag":null,"topics":["chrome","hammerspoon","lua","macos","productivity","vertical-tabs"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/mjun0812.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T02:24:22.000Z","updated_at":"2026-06-07T08:55:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mjun0812/chrome-vertical-tab-toggle-hammerspoon","commit_stats":null,"previous_names":["mjun0812/chrome-vertical-tab-toggle-hammerspoon"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mjun0812/chrome-vertical-tab-toggle-hammerspoon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjun0812%2Fchrome-vertical-tab-toggle-hammerspoon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjun0812%2Fchrome-vertical-tab-toggle-hammerspoon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjun0812%2Fchrome-vertical-tab-toggle-hammerspoon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjun0812%2Fchrome-vertical-tab-toggle-hammerspoon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjun0812","download_url":"https://codeload.github.com/mjun0812/chrome-vertical-tab-toggle-hammerspoon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjun0812%2Fchrome-vertical-tab-toggle-hammerspoon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34312347,"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-14T02:00:07.365Z","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":["chrome","hammerspoon","lua","macos","productivity","vertical-tabs"],"created_at":"2026-06-14T07:07:51.799Z","updated_at":"2026-06-14T07:07:52.548Z","avatar_url":"https://github.com/mjun0812.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chrome Vertical Tab Sidebar Toggle (Hammerspoon)\n\nA [Hammerspoon](https://www.hammerspoon.org) script that toggles Chrome's **vertical tab sidebar** with a keyboard shortcut or by hovering the mouse at the left edge of the screen.\n\nIt drives Chrome through the macOS Accessibility API — no extension, no DevTools attachment, no JavaScript injection.\n\n[日本語版 / Japanese version](./README_ja.md)\n\n![demo](./assets/demo.gif)\n\n## Features\n\n- **Keyboard trigger** — toggle the sidebar with a keyboard shortcut (default: `Cmd+B`) while Chrome is the active window.\n- **Mouse-edge trigger** — hovering the left edge of the Chrome window expands the sidebar; moving the cursor past the sidebar's right edge collapses it. Sidebars opened any other way (keyboard trigger, Chrome's own UI, etc.) are left alone.\n- **Language-agnostic detection** — localized button labels pulled directly from the Chromium source are baked in, so the script works regardless of system language.\n- **Multi-Chromium support** — Google Chrome, Beta, Canary, Dev, and Chromium are recognized by default. Add others via `TARGET_APPS`.\n- **Robust lifecycle handling** — survives Chrome focus changes, launch / quit, and system sleep / wake. A watchdog automatically revives the mouse-edge feature if monitoring stops.\n- **No shortcut hijacking** — key events are only intercepted while Chrome is the active window, so the shortcut keeps working in every other app.\n\n## Requirements\n\n- macOS\n- [Hammerspoon](https://www.hammerspoon.org) (install via Homebrew: `brew install --cask hammerspoon`)\n- Accessibility permission granted to Hammerspoon\n  (System Settings → Privacy \u0026 Security → Accessibility)\n- **Google Chrome with vertical tabs enabled.** Right-click the tab bar and choose \"Show tabs vertically\", or enable the corresponding flag in `chrome://flags`.\n\n## Quick Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/mjun0812/chrome-vertical-tab-toggle-hammerspoon/main/install.sh | bash\n```\n\n- Downloads `chrome-vertical-tab-toggle.lua` to `~/.hammerspoon/chrome-vertical-tab-toggle.lua`.\n- Appends `require(\"chrome-vertical-tab-toggle\")` to `~/.hammerspoon/init.lua` (creates the file if missing).\n- Backs up any pre-existing file as `*.backup-YYYYMMDD-HHMMSS`.\n\nFor non-interactive runs such as `curl ... | bash`, set `ASSUME_YES=1` to skip the \"overwrite existing module?\" confirmation prompt.\n\n## Manual Install\n\n1. Save this repo's `chrome-vertical-tab-toggle.lua` to `~/.hammerspoon/chrome-vertical-tab-toggle.lua`.\n2. Add the following line to `~/.hammerspoon/init.lua` (create the file if it doesn't exist):\n\n   ```lua\n   require(\"chrome-vertical-tab-toggle\")\n   ```\n\n3. Open Hammerspoon and choose **Reload Config** (or press your reload shortcut).\n4. The first time the script runs you may be prompted to grant Accessibility permission.\n\n## Configuration\n\nAll tunables live at the top of `chrome-vertical-tab-toggle.lua`.\n\n- **Shortcut**: `TOGGLE_MODS`, `TOGGLE_KEY`\n- **Enable / disable a trigger**: `FEATURES`\n- **Target apps**: `TARGET_APPS`\n- **Reaction speed / sensitivity**: `EDGE`\n- **Language coverage**: `SIDEBAR_LABELS` (add your language if it isn't already covered)\n- **`GRACE` / `DELAY` / `WATCHDOG`**: rarely need to be touched\n\n### 🚦 `FEATURES` — which triggers are active\n\n| Field             | Default | Meaning                                           |\n| ----------------- | ------- | ------------------------------------------------- |\n| `keyboardToggle`  | `true`  | Set to `false` to disable the keyboard trigger.   |\n| `mouseEdgeToggle` | `true`  | Set to `false` to disable the mouse-edge trigger. |\n\n### 🔘 `TOGGLE_MODS` / `TOGGLE_KEY` — keyboard shortcut\n\n| Field        | Default | Meaning   |\n| ------------ | ------- | --------- |\n| `cmd`        | `true`  | Cmd key   |\n| `ctrl`       | `false` | Ctrl key  |\n| `alt`        | `false` | Alt key   |\n| `shift`      | `false` | Shift key |\n| `TOGGLE_KEY` | `\"b\"`   | Main key  |\n\nMatch is **strict**: with the defaults, only plain `Cmd+B` fires — `Cmd+Shift+B` does not.\n\n### 🌐 `TARGET_APPS` — which apps count as \"Chrome\"\n\nNames of the apps for which the script should be active. Add the name of any Chromium-based browser you want to support.\n\n### 🏷️ `SIDEBAR_LABELS` — localized button labels\n\nDictionary of localized strings for the sidebar toggle button.\nIt is sourced from Chromium's translation files (message IDs `IDS_EXPAND_VERTICAL_TABS` / `IDS_COLLAPSE_VERTICAL_TABS`) for about 80 locales.\nMatching is case-insensitive.\n\n- `collapsed`: labels shown when the sidebar is currently closed (e.g. English \"Expand tabs\", Japanese \"タブを開く\").\n- `expanded`: labels shown when the sidebar is currently open (e.g. English \"Collapse tabs\", Japanese \"タブを閉じる\").\n\n### 🖱️ `EDGE` — mouse-edge trigger\n\n| Field                 | Default | Meaning                                                                                                           |\n| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |\n| `enterPx`             | `5`     | How many pixels from the window's left edge count as \"on the edge\".                                               |\n| `waitSeconds`         | `0.08`  | Hover time before the sidebar expands. Lower = snappier but more prone to misfires.                               |\n| `pollSeconds`         | `0.05`  | Mouse-position check interval. Lower = more responsive but more CPU.                                              |\n| `exitMarginPx`        | `30`    | How far past the sidebar's right edge the cursor must move to collapse it. Grazing the boundary doesn't close it. |\n| `measureDelaySeconds` | `0.2`   | Stabilization wait before measuring the sidebar's width after expand.                                             |\n\n### 🐶 `WATCHDOG` — auto-recovery monitoring\n\nAuto-recovery settings for the mouse-edge feature in case it stops responding after events like a system wake. Usually no need to change.\n\n| Field              | Default | Meaning                                                    |\n| ------------------ | ------- | ---------------------------------------------------------- |\n| `intervalSeconds`  | `2`     | Health-check interval (seconds).                           |\n| `heartbeatTimeout` | `5`     | Seconds without a heartbeat before auto-recovery kicks in. |\n\n### ⏸️ `GRACE` — trigger suppression windows\n\nSuppression durations (seconds) that prevent accidental firing right after app switches, system wake, etc. Usually no need to change.\n\n| Field          | Default | Meaning                                              |\n| -------------- | ------- | ---------------------------------------------------- |\n| `onActivate`   | `0.3`   | Suppression right after Chrome becomes active.       |\n| `onDeactivate` | `1`     | Suppression right after Chrome stops being active.   |\n| `onLaunch`     | `1.0`   | Suppression right after Chrome launches.             |\n| `onWake`       | `2.5`   | Suppression right after the system wakes from sleep. |\n| `onInit`       | `2`     | Suppression right after the script is loaded.        |\n\n### ⏱️ `DELAY` — start / stop timing\n\nDelays (seconds) between lifecycle events and starting / stopping the feature. Usually no need to change.\n\n| Field                 | Default | Meaning                                                                                             |\n| --------------------- | ------- | --------------------------------------------------------------------------------------------------- |\n| `startAfterActivate`  | `0.2`   | Delay between Chrome becoming active and starting the feature.                                      |\n| `stopAfterDeactivate` | `0.3`   | Delay between Chrome being deactivated and stopping the feature. Prevents flicker if focus returns. |\n| `restartAfterWake`    | `2`     | Delay between system wake and restarting the feature.                                               |\n| `restartGap`          | `0.5`   | Gap between stop and start during a restart.                                                        |\n| `init`                | `2`     | Delay between script load and the initial start.                                                    |\n\n## Troubleshooting\n\n- **Pressing the keyboard shortcut does nothing.**\n  Check the Hammerspoon Console for a `Sidebar button … not found` warning. Make sure the vertical tab strip is actually enabled in Chrome.\n- **The shortcut works but Chrome's own `Cmd+B` (bookmarks bar) also fires.**\n  This is expected — Chrome's built-in `Cmd+B` toggles the bookmarks bar. Change `TOGGLE_KEY` to something Chrome hasn't already bound.\n- **A new Chrome locale isn't detected.**\n  Add the exact button label strings to `SIDEBAR_LABELS.collapsed` / `expanded`. When the button can't be found, a warning is logged at most once every 30 seconds.\n\n## References\n\n- \u003chttps://github.com/Ha1baraA11/Chrome-Vertical-Tab-Sidebar-Toggle\u003e\n- \u003chttps://github.com/RotulPlastik/ChromeSidebarToggleRaycast\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjun0812%2Fchrome-vertical-tab-toggle-hammerspoon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjun0812%2Fchrome-vertical-tab-toggle-hammerspoon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjun0812%2Fchrome-vertical-tab-toggle-hammerspoon/lists"}