CmdTab

⌘Tab should switch windows, not apps. Now it does.

CmdTab is a macOS window switcher in the spirit of KDE Plasma. The stock macOS ⌘Tab cycles through applications — leaving you to hunt for the right window once you land. CmdTab cycles through windows, so every window is a first-class target: two editors, three terminals, that one Finder window you lost — each gets its own row, one keystroke away.

        ┌───────────────────────────────────────────────┐
        │   ▸ ⌨  Terminal — ~/Progetti/cmdtab           │
        │     🌐  Safari — Pull Request #42             │
        │     📝  Xcode — SwitcherOverlay.swift         │
        │     🗂  Finder — Downloads                    │
        └───────────────────────────────────────────────┘
              hold ⌘ · tap Tab to advance · release to switch

Why

The Mac app switcher is great until you live in many windows. Web devs, writers, anyone juggling several documents of the same app — you press ⌘Tab, land on the app, and then go fishing through `⌘`` or Mission Control for the actual window. CmdTab cuts the second step. One gesture, straight to the window you want.

Features

• Per-window switching — no app grouping; every window is its own row.
• Most-recently-used order — the first Tab jumps to the window you were just in, so flip-flopping between two windows is a single tap.
• Reaches everywhere — windows on other Spaces, minimized windows, and windows of hidden apps all show up and activate correctly.
• Pure keyboard flow — hold ⌘, tap Tab to advance (⌘⇧Tab to go back), arrow keys to fine-tune, release ⌘ to switch, Esc to cancel.
• Stays out of the way — the overlay appears on the screen under your pointer, ignores stray mouse hover until you actually move, and the native switcher never butts in.
• Self-healing — the event tap recovers automatically after system timeouts, so it keeps working session after session.

Requirements

• macOS 14 (Sonoma) or later.
• Accessibility permission (and Input Monitoring if prompted) — CmdTab needs these to observe the ⌘Tab gesture and to enumerate and raise windows. You grant them by hand in System Settings → Privacy & Security; CmdTab will guide you on first launch.

Build & run

swift build                              # build all targets
swift test                               # run the CmdTabCore unit tests
./Scripts/bundle.sh debug                # assemble CmdTab.app into build/
open build/CmdTab.app                     # launch it

Grant the requested permissions on first launch, then hold ⌘ and tap Tab.

Status

🛠 Active development. The core switcher works end to end — gesture capture, window enumeration across Spaces, the MRU overlay, and activation are all in place. See docs/manual-test-checklist.md for what's verified and AGENTS.md for the working agreement.

Contributing

• Read AGENTS.md — the canonical instructions for humans and AI agents.
• Capture each task as a spec using specs/TEMPLATE.md.
• Install pre-commit hooks: pip install pre-commit && pre-commit install.
• Never commit secrets; copy .env.example to .env for local config.
• Agent execution / sandbox policy: docs/agent-execution.md.

🤖 Built by agents

This project is built largely by coding agents. The numbers below are this repo's own development footprint, read from the local agent logs (Claude Code transcripts and Codex rollouts) on the machine that generated this section.

Metric	Value
Total tokens	224.3M
Token breakdown	1.3M output · 279.2K input · 6.3M cache-write · 216.4M cache-read
Agent time	~5h 42m active (78h 21m wall-clock)
Turns	1,054 assistant turns · 489 tool calls
Agents / models	Claude Code — claude-opus-4-8
As of	2026-06-22 → 2026-06-25

💡 Most of those tokens are cache reads — re-reading the growing conversation each turn — which is why the total dwarfs the tokens actually written.

Regenerated by bun Scripts/usage-self.ts (kept fresh via the repo's pre-commit hook).

License

Released under the MIT License.