Skip to content

refactor: revamp keyboard shortcuts to be more natural #341

@davidpoblador

Description

@davidpoblador

Problem

The current keyboard shortcuts feel somewhat arbitrary and could be more intuitive. They should follow macOS conventions more closely and feel natural to someone who's never read the docs.

What needs to happen

  1. Audit all shortcuts — review every shortcut for consistency and discoverability
  2. Align with macOS conventions — follow patterns users already know from Finder, Terminal.app, Safari, Xcode
  3. Resolve conflicts — ensure no shortcut collides with common terminal sequences or system shortcuts
  4. Simplify modifiers — minimize the use of triple-modifier combos (Ctrl+Shift+key); prefer Cmd-based shortcuts
  5. Group logically — shortcuts for similar actions should use similar patterns (e.g., all "open X" shortcuts share a modifier)

Places to update when shortcuts change

Per CLAUDE.md, all five of these must stay in sync:

  1. FF2App.swift (menu commands)
  2. TerminalContainerView.swift (workspace tab handling)
  3. HelpView.swift (shortcut reference)
  4. README.md (shortcut table)
  5. website/content/docs.md + translated copies (Keyboard Shortcuts section)
  6. Website shortcuts partial (website/layouts/partials/shortcuts.html)

Current shortcuts for reference

Global

| ⌘N | New workstream or project |
| ⌘Shift+N | New project |
| ⌘, | Settings |
| ⌘/ | Help |

Workstream

| ⌘Return | Focus Coding Agent |
| ⌘I | Info panel |
| ⌘E | Environment |
| ⌘T | New Terminal |
| ⌘B | New Browser |
| ⌘W | Close tab |
| ⌘L | Address bar |
| ⌘0 | Back to project |
| ⌘1-9 | Switch tab |
| ⌘Shift+[ / ] | Cycle tabs |
| Ctrl+Shift+R | Rebuild setup |
| Ctrl+Shift+S | Start/restart run |

Navigation

| Ctrl+1-9 | Switch workstream |
| ⌘Shift+O | External browser |
| ⌘Shift+E | External terminal |

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions