pcfy-my-mac

KO | EN

gitlite — search

#hacktoberfest #java #python #javascript #reactjs #react #sql #machine-learning #html #dart #flutter #bootstrap

★ 30 Open GitHub ↗

Get a PC-like (Windows/Linux) experience on macOS - PC-style keyboard shortcuts and window management, powered by Karabiner-Elements, AltTab & Rectangle.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# PC'fy my Mac

All-in-one project to help you get a **PC**-like experience (known from **Windows** or **Linux** systems) on your **macOS**

</div>
</div>

---

This is a set of configuration files for open source applications
like [Karabiner-Elements](https://karabiner-elements.pqrs.org/), [AltTab](https://alt-tab-macos.netlify.app/)
and [Rectangle](https://rectangleapp.com/)
wrapped into an easy-to-use CLI tool that automates the whole setup process. It’s an ideal solution for
those who are new to macOS and for users who frequently switch between macOS and Windows or Linux.
This is also perfect for you if the macOS out-of-the-box workspace management isn’t really your thing.

You can think of this project as [Kinto](https://github.com/rbreaves/kinto), but in reverse and with more features.

## Features

- **PC-style keyboard shortcuts** for system, text editing and browser (Chromium-based) actions - `Ctrl+C`/`Ctrl+V`, word navigation, `Home`/`End`, `Alt+F4` and many more
- Battle-tested **JetBrains tools keymaps** (IntelliJ IDEA, PyCharm, GoLand, Android Studio, Fleet)
- **Quick application launching** with the Win/Opt key - just like the Start menu on PC
- **Snapping windows** using Win/Opt + ←/→/↑/↓ shortcut
- **Better window switcher** - move between windows with the Alt + Tab shortcut
- **Configurable** app launcher (Spotlight, Launchpad or Alfred) and terminal (Apple Terminal, iTerm, Warp or Wave)
- **Everything works on any keyboard layout out of the box - you can use both the built-in Mac and external PC keyboards at the same
  time**

## Requirements

- **macOS** (Apple Silicon or Intel)
- The required apps - [Karabiner-Elements](https://karabiner-elements.pqrs.org/), [AltTab](https://alt-tab-macos.netlify.app/), [Rectangle](https://rectangleapp.com/) and `jq` - are **installed automatically** via [Homebrew](https://brew.sh/) if missing (you'll be asked for confirmation first)

## Installation

### [Homebrew](https://brew.sh/)

```shell
brew install raxigan/tap/pcfy-my-mac
pcfy-my-mac
```

> Remember about executing the binary after every **_brew upgrade_** in order to apply the changes from new release.

### Script

May require [special terminal permissions](#Terminal-dev-permissions)

```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/raxigan/pcfy-my-mac/main/pcfy.sh)"
```

### Go binary

```shell
go install github.com/raxigan/pcfy-my-mac@latest
pcfy-my-mac
```

### From source

```shell
git clone https://github.com/raxigan/pcfy-my-mac
cd pcfy-my-mac
go run pcfy.go
```

## Options

| Flag                      | Description                                                                                                                                        |
|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| **--help**                | Show usage                                                                                                                                         |
| **--params** <params.yml> | Path to your YAML file containing installation parameters. Allows to run the tool in non-interactive mode. Use below option to see the file format |
| **--show-sample-yaml**    | Show sample YAML config which can be used as the input for above flag                                                                              |
| **--verbose**             | Enable verbose mode. All performed operations will be logged out to console                                                                        |
| **--version**             | Show version information                                                                                                                           |

## Configuration

The tool can be run in two ways:

- **Interactive mode** - just run `pcfy-my-mac` and answer the on-screen prompts.
- **Non-interactive mode** - pass a YAML file with `--params my-config.yml` to run the whole setup unattended (handy for reproducible setups across machines). Generate a starting point with `pcfy-my-mac --show-sample-yaml`.

Every parameter is optional - anything you omit is asked for interactively (except `keyboard-type`, which is available through the YAML file only).

| Parameter          | Description                                                                 | Allowed values                                                                                                  |
|--------------------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| `app-launcher`     | Application opened with the Win/Opt key                                      | `spotlight`, `launchpad`, `alfred`, `none`                                                                      |
| `terminal`         | Terminal opened with `Ctrl + Alt + T`                                       | `default` (Apple Terminal), `iterm`, `warp`, `wave`, `none`                                                     |
| `keyboard-layout`  | Layout of your external keyboard, used to adjust the setup                  | `pc`, `mac`, `none`                                                                                             |
| `keyboard-type`    | Physical keyboard type written to the Karabiner virtual keyboard (omit to keep Karabiner's default) | `ansi`, `iso`, `jis`                                                                  |
| `system-settings`  | Optional macOS tweaks to apply                                              | Dock auto-hide, Dock minimize animation, `Home`/`End` keys, Finder improvements (see the sample YAML)           |
| `keymaps`          | JetBrains IDEs to install the keymap for                     | `IntelliJ IDEA Ultimate`, `IntelliJ IDEA Community Edition`, `PyCharm`, `PyCharm Community Edition`, `GoLand`, `Android Studio`, `Fleet` |
| `blacklist`        | App bundle identifiers to hide from the AltTab window switcher              | e.g. `com.spotify.client`, `com.apple.finder`                                                                   |

> Your existing Karabiner-Elements configuration is backed up before any changes are made, so you can always revert.

## Shortcut list

The following shortcuts are available right after installation. Note that shortcuts from the tools' keymaps are not
listed here.

For Mac keyboard layout:

- The **Win** key corresponds to **Opt**
- The **Alt** key corresponds to **Cmd**

<details>
  <summary><b>Shortcut list - click to expand</b></summary>

```txt
  Alt + Tab                   # Switch to next window
  Alt + Shift                 # Switch to previous window (only when switcher is opened)
  Win + Left/Right            # Snap window to left/right
  Win + Up/Down               # Maximize/almost maximize window
  Ctrl + Left/Right           # Move to previous/next word
  Ctrl + Shift + Left/Right   # Select previous/next word
  Home/End                    # Move to beginning/end of line
  Ctrl + Home/End             # Move to beginning/end of document
  Shift + Home/End            # Move to beginning/end of line with selection
  Ctrl + Shift + Home/End     # Move to beginning/end of document with selection
  Ctrl + LMB                  # Select item
  Ctrl + Shift + LMB          # Select multiple items
  Ctrl + +/-                  # Zoom in/out in browser, Slack, Teams
  Ctrl + A                    # Select all
  Ctrl + B                    # Bold
  Ctrl + C                    # Copy item, interrupt current process in terminal
  Ctrl + F                    # Find
  Ctrl + I                    # Italic
  Ctrl + N                    # New...
  Ctrl + L                    # Open location in browser
  Ctrl + O                    # Open...
  Ctrl + R                    # Replace/Reload
  Ctrl + S                    # Save
  Ctrl + T                    # New browser/terminal tab
  Ctrl + Shift + T            # Reopen last closed browser/terminal tab
  Ctrl + U                    # Underline
  Ctrl + V                    # Paste item
  Ctrl + W                    # Close browser tab
  Ctrl + X                    # Cut
  Ctrl + Y                    # Redo
  Ctrl + Z                    # Undo
  Ctrl + Tab                  # Move to next browser/terminal tab
  Ctrl + Shift + Tab          # Move to previous browser/terminal tab
  Ctrl + Shift + Z            # Redo
  Win + L                     # Lock screen
  F2                          # Rename file in Finder
  F3/Shift + F3               # Move to next/previous occurrence in text
  Alt + F4                    # Quit application
  F5                          # Reload page in browser
  Win                         # Open preferred application launcher
  Ctrl + Alt + T              # Open preferred terminal
  ```

</details>

## Version compatibility
- Fleet 1.39.118+

## Additional notes

- Only tools that have been installed via the JetBrains Toolbox are supported **[JetBrains keymaps only]**
- Ensure your modifier keys are set to default in _System Settings > Keyboard > Keyboard Shortcuts... > Modifier Keys_
- Ensure the function keys are enabled in the system settings in order to use shortcuts based on them:
- There is 1 alternative shortcut provided for Mac keyboard layout (as there is no **Insert** key):
    - **Alt/Cmd + Insert** (New file in JB tools) → **Alt/Cmd + Enter**

![function-keys.png](https://raw.githubusercontent.com/raxigan/pcfy-my-mac/main/.docs/resources/f-keys.png)

### Terminal dev permissions

**Necessary only if you install it by shell script**. The binary is not signed, so macOS may not let you run it without
the following permissions for your terminal. Just go to *System Settings* > *Privacy & Security* > *Developer Tools*
and enable it:

![terminal_permissions.png](https://raw.githubusercontent.com/raxigan/pcfy-my-mac/main/.docs/terminal-permissions.png)

## Troubleshooting

- **Problem**: Shortcuts from [the list](#shortcut-list) do not work

**Solution**: Verify the **PCfy** profile is selected in Karabiner-Elements:

![karabiner-profile.png](https://raw.githubusercontent.com/raxigan/pcfy-my-mac/main/.docs/karabiner-profile.png)

Also check if **Modify events** option for your keyboard is enabled in *Karabiner-Elements* > *Settings* > *Devices*:

![device-enabled.png](https://raw.githubusercontent.com/raxigan/pcfy-my-mac/main/.docs/device-enabled.png)

- **Problem**: On pressing '~' (tilde), § (section sign) is entered instead. This might happen if your external keyboard and the built-in one are of different types: ANSI/ISO/JIS

**Solution**: Set the matching keyboard type (usually **ANSI**) - either via the [`keyboard-type`](#configuration) parameter, or manually in `Karabiner-Elements` → `Virtual Keyboard`

![karabiner-virtual-kb.png](https://raw.githubusercontent.com/raxigan/pcfy-my-mac/main/.docs/karabiner-virtual-kb.png)

## Contributing
- Ask a question or share your ideas in [Discussions](https://github.com/raxigan/pcfy-my-mac/discussions)
- Create & comment issues in [Issues](https://github.com/raxigan/pcfy-my-mac/issues)

## Acknowledgments

- [@tekezo](https://github.com/tekezo) for [Karabiner-Elements](https://karabiner-elements.pqrs.org/)
- [@lwouis](https://github.com/lwouis) for [AltTab](https://alt-tab-macos.netlify.app/)
- [@rxhanson](https://github.com/rxhanson) for [Rectangle](https://rectangleapp.com/)
- [@rux616](https://github.com/rux616) for [karabiner-windows-mode](https://github.com/rux616/karabiner-windows-mode)
- [@serhii-londar](https://github.com/serhii-londar)
  for [open-source-mac-os-apps](https://github.com/serhii-londar/open-source-mac-os-apps)

pcfy-my-mac

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README