This is an opinionated dev setup for Mac and Ubuntu.

• Keyboard -> Input Sources -> change language to CMD + Space
• Keyboard -> Spotlight - change to CMD + Shift + Space
• Keyboard -> Function keys -> Turn on "Use F1.. as function keys"
• Keyboard -> Mission control -> turn off Mission Control and Application windows, Show Desktop
  • change move left/right a space to use CMD instead of CTRL (so that tmux leader key would work fine)
• Mouse -> disable natural scrolling
• Keyboard -> Key Repeat -> Fast
• Keyboard -> Delay Until Repeat -> Short
• Keyboard -> Text Input -> Disable most things
• Keyboard -> Accessibility -> Disable VoiceOver
• Control Center
  • Sound -> Always Show in Menu Bar
  • Battery -> Show Percentage
  • Date -> Display time with seconds
  • Weather -> Show in menu

run tmux and install it: F1 + I

• Launch at setup
• Open with Shift+CMD+V (shifted paste)
• Fuzzy search
• Paste automatically

Karabiner-Elements enables custom keyboard shortcuts for Windows/Linux compatibility.

Installation:

./macos/install-karabiner.sh

Configured shortcuts:

• Ctrl Insert → Copy (maps to Cmd C)
• Shift Insert → Paste (maps to Cmd V)

Manual setup required after installation:

1. Open System Settings → Privacy & Security → Accessibility

2. Grant permission to karabiner_grabber and karabiner_observer

3. You may need to restart your Mac for changes to take effect

4. In karabiner-elements settings -> virtual keyboard, change your keyboard to ANSI (to have ~ character working correctly)

Note: These shortcuts require a keyboard with an Insert key (common on external/Windows keyboards). If using a Mac keyboard without Insert, you can remap another key in Karabiner's UI.

• § - center window
• Shift § - restore window position
• Shift + - increase window
• Shift - - decrease window
• Shift F1 - move window left-top
• Shift F2 - move window right-top
• Shift F3 - move window left-bottom
• Shift F4 - move window right-bottom

• Cmd + - increase font
• Cmd - - decrease font
• Cmd t - open tab
• Cmd n - open new window

To install, run: ./macos/install-ui-apps.sh

Keyboard customization:

./macos/install-karabiner.sh  # Install Karabiner-Elements for custom keyboard shortcuts

Others need manual installation:

• Goland
• Docker4Mac
• Postman
• OpenVPN
• Discord
• Monocle to access k8s logs
• Microsoft TODO

• Install Jetbrains Mono Nerdfont or original Jetbrains Mono
  • Update iTerm and IDEs to use it to see nice icons
  • Use ligatures

git config --global user.name "Artjom Kurapov"
git config --global user.email "artkurapov@gmail.com"
git config --global pull.rebase false

# generate key for github
ssh-keygen -t rsa -b 4096 -C "artkurapov@gmail.com"
open "https://github.com/settings/keys"
cat ~/.ssh/id_rsa.pub

chmod +x install.sh

# Optional: Backup existing configs before installation
./backup.sh

git clone git@github.com:tot-ra/ai-workstation.git ~/git/ai-workstation
~/git/ai-workstation/install.sh
echo "source ~/git/ai-workstation/mount.sh" >> ~/.zshrc

# link nvim and tmux configs to be linked to github repo
ln -s ~/git/ai-workstation/.tmux.conf ~/.tmux.conf
ln -s ~/git/ai-workstation/.config/nvim ~/.config/nvim

# now add this key to github --> https://github.com/settings/ssh/new

Features:

• ✅ Idempotent - safe to run multiple times
• 📝 Detailed logging in ~/.workstation-logs/
• 🔄 Version management via versions.env
• 🛡️ Security best practices built-in
• 💾 Backup script for existing configs

• run tmux and run F1 I to install plugins
• run lazygit first time to activate
• run nvim and from cmd mode run (where you'll need to install plugins):

:Lazy
:LazyExtras
:Copilot auth
:Mason

Edit versions.env to customize software versions:

# Example: Change Node.js default version
NODE_VERSION_DEFAULT="18"

# Example: Use different Go version
GO_VERSION="1.21"

workstation/
├── install.sh              # Main installation script (Mac)
├── backup.sh               # Backup existing configurations
├── common-functions.sh     # Shared helper functions
├── versions.env            # Version management
├── checksums.env           # Security checksums
├── install-*.sh            # Component-specific installers
├── .config/                # Application configs
│   ├── nvim/              # Neovim/LazyVim config
│   └── wezterm/           # Wezterm terminal config
├── ubuntu/                 # Ubuntu-specific scripts
├── CHANGELOG.md            # Version history
├── SECURITY.md             # Security guidelines
└── README.md               # This file

• F1 - tmux
• F12 - toggle fullscreen (wezterm)

Leader (F1) and:

• : new - create new session

• w - choose window

• * - clears history and terminal

• ? - show key bindings

• r - reload config

• I - install plugins

• : - command mode

• $ - rename session

• d - detach from session

• [ - enter copy mode

  • Space - start selection
  • Enter - copy selection
  • ] - paste selection

• tmux ls - list sessions
• tmux new -s my-session - create session
• tmux a - attach to new session
• tmux a -t my-session - attach to session by name

• F1 + - create window
• F1 - - split window horizontally
• F1 | - split window vertically
• Ctrl Shift right - next window
• Ctrl Shift left - previous window
• , - rename window
• . - move window

• Ctrl arrows - moves between panes (including within nvim)
• " - split window to panes horizontally
• % - split window to panes vertically
• z - zoom pane (toggle)
• ! - move pane to own window
• o - switch session (interactive with plugin)

• F3 - find string
• F4 - find file
• :50 - go to line 50
• F11 - toggle DB UI
• Space is set as leader
  • gd - go to definition
  • e - toggle tree view
• Tab - accept completion
• Alt left/right - switch between tabs
• Alt up - close tab
• Alt down - pin tab
• Ctrl I - go to previous location
  • Ctrl O - go to next location

• s - jump to characters (flash plugin)
• gg - go to top of the file
  • G - go to end of the file
• 20G - go to line 20
• 5j - go up 5 lines
  • 5k - go down 5 lines
• w jump to next word
  • b jump back to previous word
• f - find character
  • ; next
• m - bookmark line (for harpoon)
  • TAB - toggle bookmark list
• / - search
  • n - next hit
• f( - jump to next bracket

• za - Toggle between closing and opening the fold under the cursor.
• zR - Open all folds in the current buffer.
• zM - Close all folds in the current buffer.

• gcc - comment line

:%s/from/to/gc

• F2 - search/replace (nvim) with LSP
• I - switch to insert mode + go to beginning of the line
• A - switch to insert mode + go to end of the line
• i - switch to insert mode
• o - switch to insert mode + add new line after current one

• y - copy (yield)
• p - paste
• d - cut
• dd - delete line
• u - undo
• w - select word

• Space gg - toggle lazygit

Problem: nvm: command not found after running install script

Solution:

# Restart your terminal or source the config
source ~/.zshrc

# Verify NVM is loaded
command -v nvm

Problem: Tmux plugins don't install when pressing F1 + I

Solution:

# Ensure TPM is installed
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Restart tmux
tmux kill-server
tmux

# Press F1 + I to install plugins

Problem: Homebrew packages fail to install

Solution:

# Update brew
brew update

# Diagnose issues
brew doctor

# Check installation logs
cat ~/.workstation-logs/install-*.log

Problem: Neovim starts but plugins are missing

Solution:

# Open neovim and run
nvim

# In nvim command mode, run:
:Lazy
:Lazy sync

# Check for errors
:checkhealth

Problem: Tab completion doesn't work in zsh

Solution:

# Fix permissions
compaudit | xargs chmod g-w,o-w

# Rebuild completion cache
rm ~/.zcompdump*
exec zsh

Problem: Cannot push/pull from GitHub

Solution:

# Check if SSH key exists
ls -la ~/.ssh/id_rsa.pub

# If not, generate one
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

# Add to GitHub: https://github.com/settings/ssh/new
cat ~/.ssh/id_rsa.pub

Problem: kubectl or docker commands fail

Solution:

# Ensure OrbStack is running
open -a OrbStack

# Check kubectl context
kubectl config current-context

# Verify docker
docker ps

Problem: Wrong Python or Node version active

Solution:

# For Node (using nvm)
nvm use 20
nvm alias default 20

# For Python (if using pyenv)
pyenv global 3.11

Problem: Terminal prompt doesn't show p10k theme

Solution:

# Reconfigure p10k
p10k configure

# Ensure it's in .zshrc
grep powerlevel10k ~/.zshrc

# If missing, add it
echo "source $(brew --prefix)/share/powerlevel10k/powerlevel10k.zsh-theme" >> ~/.zshrc

Problem: Tmux doesn't use custom config

Solution:

# Ensure symlink exists
ls -la ~/.tmux.conf

# If not, create it
ln -sf ~/git/workstation/.tmux.conf ~/.tmux.conf

# Reload tmux config (inside tmux)
# Press F1 + r

Problem: Custom nvim config conflicts with LazyVim

Solution:

# Backup your config
mv ~/.config/nvim ~/.config/nvim.backup

# Link to workstation config
ln -s ~/git/workstation/.config/nvim ~/.config/nvim

# Restart nvim and run
:Lazy restore

Problem: Control+Insert and Shift+Insert shortcuts don't work

Solution:

# Check if Karabiner is running
ps aux | grep karabiner

# Verify permissions in System Settings
# Go to: Privacy & Security → Accessibility
# Ensure karabiner_grabber and karabiner_observer are checked

# Check if your keyboard has an Insert key
# External/Windows keyboards usually have it
# Mac keyboards typically don't

# View current configuration
cat ~/.config/karabiner/karabiner.json

# Restart Karabiner
killall karabiner_grabber karabiner_observer
# Or restart from the menu bar icon

# If still not working, you may need to restart your Mac

Problem: Terminal takes long to open

Solution:

# Profile zsh startup
time zsh -i -c exit

# Disable plugins temporarily to identify culprit
# Comment out plugins in ~/.zshrc one by one

# Common culprits:
# - nvm (use lazy loading)
# - Too many plugins

Problem: Neovim takes several seconds to open

Solution:

# Profile nvim startup
nvim --startuptime startup.log

# Review which plugins are slow
cat startup.log | sort -k2 -n

# Consider lazy-loading slow plugins

If you're still stuck:

1. Check logs: Installation logs are in ~/.workstation-logs/
2. Search issues: Check GitHub issues
3. Create issue: Open a new issue with:
   • Your OS version (sw_vers on Mac, lsb_release -a on Ubuntu)
   • Error messages from logs
   • Steps to reproduce

# Check what's using a port
lsof -i :3000

# Check system info (Mac)
sw_vers
system_profiler SPSoftwareDataType

# Check disk space
df -h

# Check running processes
ps aux | grep <process-name>

# View installation logs
tail -f ~/.workstation-logs/install-*.log

# Check brew services
brew services list