{"id":50777206,"url":"https://github.com/searayca/terminal-switcher","last_synced_at":"2026-06-12T01:00:38.977Z","repository":{"id":364157720,"uuid":"1260786215","full_name":"searayca/terminal-switcher","owner":"searayca","description":"A lightweight macOS menu-bar app to see and jump between Apple Terminal windows by project.","archived":false,"fork":false,"pushed_at":"2026-06-11T22:57:03.000Z","size":968,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T23:07:40.592Z","etag":null,"topics":["developer-tools","macos","menu-bar-app","menubar","productivity","swift","terminal"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/searayca.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"custom":["https://buymeacoffee.com/terminalswitcher"]}},"created_at":"2026-06-05T21:48:35.000Z","updated_at":"2026-06-11T22:57:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/searayca/terminal-switcher","commit_stats":null,"previous_names":["searayca/terminal-switcher"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/searayca/terminal-switcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/searayca%2Fterminal-switcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/searayca%2Fterminal-switcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/searayca%2Fterminal-switcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/searayca%2Fterminal-switcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/searayca","download_url":"https://codeload.github.com/searayca/terminal-switcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/searayca%2Fterminal-switcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34224103,"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-11T02:00:06.485Z","response_time":57,"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":["developer-tools","macos","menu-bar-app","menubar","productivity","swift","terminal"],"created_at":"2026-06-12T01:00:22.882Z","updated_at":"2026-06-12T01:00:38.963Z","avatar_url":"https://github.com/searayca.png","language":"Swift","funding_links":["https://buymeacoffee.com/terminalswitcher"],"categories":[],"sub_categories":[],"readme":"\u003c!-- Copyright (c) 2025-2026 Greg Ames/Ames \u0026 Associates. Licensed under the Coffee Right License — see LICENSE. --\u003e\n\u003c!-- Project: Terminal Switcher | Filename: README.md --\u003e\n# Terminal Switcher\n\nA lightweight macOS menu-bar app that lists every open Apple Terminal window — labeled by project — and jumps to any of them in one click.\n\n![Terminal Switcher menu showing open Terminal windows grouped by project](docs/screenshot.png)\n\n**Like it? [Buy me a coffee ☕](https://buymeacoffee.com/terminalswitcher)**\n\n## Features\n\n- Menu-bar dropdown listing all open Apple Terminal windows.\n- Click (or drag and release) on a window to bring it to the front.\n- A persistent, auto-sizing floating panel of windows you can keep on screen.\n- Project names resolved automatically from each window's working directory.\n- **New Terminal Window** to open a fresh shell.\n- **New Window in Project ▸** submenu that opens a shell in any project under\n  your chosen Projects Folder.\n- Fast: window data is gathered with batched `ps`/`lsof` (just 3 subprocess\n  calls) and served from a background-refreshed cache, so the UI stays snappy.\n- **Start at Login** toggle — one click and it is simply *always there*.\n- **Check for Updates** — manual, one-click self-update from the About panel.\n- Deliberately small: a single Swift binary, no Dock icon, negligible memory\n  footprint, and no network activity — except when you click\n  **Check for Updates**.\n\n## Why I Built It\n\nI use Claude Code every day, all day — and almost never on just one project. At\nany given moment I have four, five, six Terminal windows open, each one running\na Claude Code session in a different project: one fixing a bug in a web app,\none processing documents, one doing infrastructure work.\n\nThe problem: **those windows all look identical.** Finding the right one meant\ngoing down to the Dock, clicking and holding (or Option-clicking) the Terminal\nicon, squinting at a list of near-identical window titles, picking one,\nrealizing it was the wrong one, and going back to do it again. Dozens of times\na day. It was cumbersome, it broke my concentration, and the time lost added up.\n\nWhat I actually wanted to know at a glance was simple:\n\n1. *Which project is each window in?*\n2. *What is each session working on right now?*\n\nSo Terminal Switcher answers exactly those two questions, from a menu that is\nalways in the same place at the top of the screen. One click to see everything,\none click to be in the right window. It turned a recurring daily annoyance into\na non-event — and if you run multiple terminal sessions for any reason (Claude\nCode or otherwise), it will likely do the same for you.\n\n## Install\n\n### Option 1 — Quick install (any Mac — Intel or Apple Silicon)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/searayca/terminal-switcher/main/install.sh | bash\n```\n\nWorks on both Intel and Apple Silicon Macs — it installs the prebuilt\nuniversal app from the latest release, no Homebrew or Xcode needed.\n\n### Option 2 — Homebrew\n\n```bash\nbrew install searayca/tap/terminal-switcher\n```\n\nThen follow the caveats Homebrew prints to copy the app into `~/Applications`\nand launch it.\n\n### Option 3 — Build from source\n\nRequires macOS 13+ and a Swift toolchain — either Xcode or just the Command\nLine Tools (`xcode-select --install`).\n\n```bash\ngit clone https://github.com/searayca/terminal-switcher.git\ncd terminal-switcher\n./build.sh\n```\n\n`build.sh` compiles a release build, assembles it into a `.app` bundle at\n`/Applications/Terminal Switcher.app`, ad-hoc signs it (so the Automation\npermission can attach to a stable identity), and launches it.\n\n### Option 4 — Download\n\nGrab `Terminal-Switcher-vX.Y.Z-universal.zip` from the\n[Releases page](https://github.com/searayca/terminal-switcher/releases),\nunzip it, and move `Terminal Switcher.app` to `~/Applications`. The\nrelease zip is a universal binary (Intel + Apple Silicon).\n\n\u003e **Gatekeeper note:** the app is ad-hoc signed but **not notarized**, so\n\u003e macOS will block a normal double-click launch of the downloaded copy.\n\u003e **Right-click (or Control-click) the app → Open → Open** the first time;\n\u003e after that it launches normally. Building from source or installing via\n\u003e Homebrew avoids this entirely.\n\n## First launch\n\nThe first time Terminal Switcher tries to list or switch windows, macOS will\nprompt:\n\n\u003e **\"Terminal Switcher\" wants access to control \"Terminal\".**\n\nThis is the standard macOS **Automation** permission — the app drives\nTerminal via Apple Events to enumerate windows and bring the one you pick to\nthe front. **You must click \"Allow\"** or the app cannot function.\n\nIf you declined the prompt (or want to change it later), re-enable it in\n**System Settings → Privacy \u0026 Security → Automation → Terminal Switcher →\nTerminal**. The app's menu also has **Open Automation Settings…** to jump\nstraight there.\n\n## Usage\n\nClick the 🖥️ icon in the menu bar to open the dropdown. Release the click on a\nwindow row to switch to that window. The dropdown also includes:\n\n- **New Terminal Window** — open a fresh shell.\n- **New Window in Project ▸** — open a shell in any project under your\n  Projects Folder (see below).\n- **Show Floating Panel** — show the persistent floating window list.\n- **Set Projects Folder…** — choose the folder that contains your projects.\n- **Start at Login** — toggle launching the app automatically at login.\n- **Open Automation Settings…** — jump to the macOS Automation privacy pane.\n- **About Terminal Switcher** — version info, links, and Check for Updates.\n- **Check for Updates…** — manually check GitHub for a newer release.\n- **Quit Terminal Switcher**.\n\nNote: the app drives Apple `Terminal.app` only; it does not support iTerm or\nother terminal emulators.\n\n## Floating Panel\n\nFor heavy switching sessions, **Show Floating Panel** opens an always-on-top\nwindow listing the same Terminal windows as the dropdown — but it stays on\nscreen, so you can hop between sessions with single clicks instead of opening\nthe menu each time. The panel sizes itself to its list, refreshes live as\nwindows open, close, and change directory, stays put without stealing focus\nfrom your terminal, and remembers its position between launches. Close it with\nits close button; reopen it from the menu any time.\n\n## Where the app lives\n\nTerminal Switcher is a **menu-bar-only** app: it has no Dock icon and no Dock\npresence — just the 🖥️ icon at the top of your screen. If you quit it (or\nwonder where it went), relaunch it from `Terminal Switcher.app` in\n`/Applications` or `~/Applications` (wherever you installed it), or via\nSpotlight — press ⌘-Space and type \"Terminal Switcher\".\n\n## How it finds your projects\n\n**Window labels.** Each open window's project is simply the working directory\nof whatever is running in it — Terminal Switcher detects the foreground\nprocess on each window's tty and resolves its current directory. No\nconfiguration needed.\n\n**New Window in Project.** This submenu lists the subfolders of your\n**Projects Folder** — the one folder that contains your project folders.\nNothing is assumed: the first time you pick **Set Projects Folder…** (from\nthe main menu, or from the submenu itself when no folder is set yet), a short\ndialog explains what the folder is for, then a standard chooser lets you pick\nit. You can change it any time from the same menu item.\n\n**Claude Code bonus.** If you use Claude Code and have a\n`~/.claude/projects.md` file, its project nicknames (`## \"Name\"` headings\nwith `**Path:**` entries) are picked up automatically and used as friendly\nwindow labels. No file? Windows are labeled by folder name — see the next\nsection for the format.\n\n## Project nicknames (optional)\n\nWindow labels can use friendly project nicknames instead of bare folder names.\nNicknames come from an optional `~/.claude/projects.md` file that maps folder\npaths to names. Without that file, each window is simply labeled by its\nworking-directory folder name.\n\nThe format is a Markdown heading with the nickname in quotes, followed by a\n`**Path:**` line pointing at the project's absolute directory:\n\n```markdown\n## \"KDreamz\"\n**Path:** `/Users/you/PycharmProjects/karaoke-dreamz/`\n```\n\nThe **New Window in Project ▸** submenu scans your chosen Projects Folder —\nset it with **Set Projects Folder…** in the menu (see\n[How it finds your projects](#how-it-finds-your-projects)).\n\n## Start at Login\n\nTerminal Switcher is most useful when it's simply always there, so:\n\n- The menu has a checkable **Start at Login** item — click it to toggle\n  launching the app automatically when you log in.\n- On first launch, the app offers this once: *\"Start Terminal Switcher at\n  login?\"* — choose **Start at Login** or **Not Now**. Either way it never\n  asks again; you can change your mind any time from the menu.\n- When enabled, the app appears under **System Settings → General →\n  Login Items** like any other login item, and you can also turn it off there.\n\n\u003cdetails\u003e\n\u003csummary\u003eAdvanced: launchd LaunchAgent alternative\u003c/summary\u003e\n\nIf you prefer a supervised launchd LaunchAgent instead of a login item:\n\n```bash\ncp com.greg.terminal-switcher.plist ~/Library/LaunchAgents/\nlaunchctl load -w ~/Library/LaunchAgents/com.greg.terminal-switcher.plist\n```\n\nUse one mechanism or the other — both work, but you only need one.\n\u003c/details\u003e\n\n## About \u0026 updates\n\n**About Terminal Switcher** (in the menu) shows the version you're running,\nlinks to the website, GitHub, and Buy Me a Coffee, and a **Check for Updates**\nbutton.\n\nUpdates are **manual-only** — the app makes **no network calls except when you\nclick Check for Updates** (from the About panel or the menu item). When you do,\nit asks GitHub for the latest release and either confirms you're up to date or\noffers **Update Now** (downloads the new version via the install script,\nreplaces the app in place, and relaunches it — settings are kept),\n**Release Notes**, or **Later**. No background checks, no phoning home, ever.\n\n## Uninstall\n\nOne-liner — stops the app, removes `Terminal Switcher.app` from\n`/Applications` and `~/Applications`, and removes the LaunchAgent if present:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/searayca/terminal-switcher/main/install.sh | bash -s -- --uninstall\n```\n\nOr by hand: quit Terminal Switcher from its menu, delete\n`Terminal Switcher.app` from your Applications folder, and remove\n`~/Library/LaunchAgents/com.greg.terminal-switcher.plist` if you created one.\n\n## How it works\n\nAppleScript (run via `osascript`) asks Terminal for each window's id, title, and\ntty. A single batched `ps` plus one `lsof` call then resolve each window's\ncurrent working directory from its tty. The UI is a SwiftUI/AppKit menu-bar app\nbuilt on `NSStatusItem` and a non-activating `NSPanel`, so it can show and\nswitch windows without stealing focus from your terminal.\n\n## A Tip of the Hat to Andy Hertzfeld\n\nIn 1985, Andy Hertzfeld — one of the original Macintosh software wizards — wrote\n[Switcher](https://www.folklore.org/StoryView.py?story=Switcher.txt), the program\nthat first let a Mac keep several applications open at once — MacWrite, MacPaint,\nExcel, Microsoft Word, HyperCard — and flip between them instantly, without\nquitting one program to launch another. Every application switcher since,\nincluding this little one, walks in those footsteps. Thank you, Andy.\n\nMore about Andy: [Wikipedia](https://en.wikipedia.org/wiki/Andy_Hertzfeld) ·\n[folklore.org](https://www.folklore.org/) — his site of original-Macintosh stories.\n\n## Contact \u0026 Support\n\nQuestions, bug reports, and enhancement requests are welcome:\n\n- Open an issue on [GitHub Issues](https://github.com/searayca/terminal-switcher/issues)\n- Or email [terminal-switcher@ac44.com](mailto:terminal-switcher@ac44.com)\n\n## License\n\nReleased under the **Coffee Right License** — free to use, modify, and\nredistribute; if you like it, [buy Greg a coffee ☕](https://buymeacoffee.com/terminalswitcher).\nSee [LICENSE](LICENSE) for the full text.\n\nCopyright © 2025-2026 Greg Ames.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsearayca%2Fterminal-switcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsearayca%2Fterminal-switcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsearayca%2Fterminal-switcher/lists"}