👾 cyperx's Dotfiles

id

README

👾 cyperx's Dotfiles

          ▄████▄  ▓██   ██▓ ██▓███  ▓█████  ██▀███  ▒██   ██▒
         ▒██▀ ▀█   ▒██  ██▒▓██░  ██▒▓█   ▀ ▓██ ▒ ██▒▒▒ █ █ ▒░
         ▒▓█    ▄   ▒██ ██░▓██░ ██▓▒▒███   ▓██ ░▄█ ▒░░  █   ░
         ▒▓▓▄ ▄██▒  ░ ▐██▓░▒██▄█▓▒ ▒▒▓█  ▄ ▒██▀▀█▄   ░ █ █ ▒ 
         ▒ ▓███▀ ░  ░ ██▒▓░▒██▒ ░  ░░▒████▒░██▓ ▒██▒▒██▒ ▒██▒
         ░ ░▒ ▒  ░   ██▒▒▒ ▒▓▒░ ░  ░░░ ▒░ ░░ ▒▓ ░▒▓░▒▒ ░ ░▓ ░
           ░  ▒    ▓██ ░▒░ ░▒ ░      ░ ░  ░  ░▒ ░ ▒░░░   ░▒ ░
         ░         ▒ ▒ ░░  ░░          ░     ░░   ░  ░    ░  
         ░ ░       ░ ░                 ░  ░   ░      ░    ░  
         ░         ░ ░

A curated collection of configuration files for a complete development environment, organized as a macOS + Linux monorepo: macOS configs live in mac/, Linux (Omarchy/Hyprland) configs in linux/. This setup creates a beautiful, efficient, and highly customized workflow centered around tiling window management, terminal productivity, and modern development tools.

📚 Documentation Hub

🚀 Quick Start: Installation • 🔧 Components: Detailed Guide • ⌨️ Keybinds: Reference • 🔄 Workflows: Integration Guide

Document	Purpose	For
📋 Components Guide	Detailed documentation for all 15+ tools	Understanding each component
⌨️ Keybinds Reference	Complete keybindings across all tools	Quick reference and lookup
📝 Neovim Keybinds	Comprehensive Neovim mappings	Editor workflow mastery
🔄 Workflow Guides	Cross-tool integration patterns	Learning tool combinations
🧠 Local MLX Gemma 4	Local Gemma 4 on MLX for OpenClaw/Hermes + MTP optimization	Running a fast local agent model
🔧 Maintenance Guide	Validation, troubleshooting, updates	System reliability
🤖 Claude Documentation	Claude Code guidance & agent guidelines	AI-assisted development

🌟 Features

🪟 Tiling Window Management: Aerospace tiling window manager
🔲 Window Borders: JankyBorders for visual window separation
🎨 Beautiful Terminal: Ghostty with custom shaders and Starship prompt
⌨️ Advanced Key Remapping: Kanata with home row mods + Karabiner-Elements
📊 System Monitoring: SketchyBar for elegant macOS menu bar replacement
🚀 Terminal Multiplexing: Tmux with Catppuccin theme and advanced plugins
⚡ Modern Shell: Zsh with FZF, syntax highlighting, and intelligent completions
🛠️ Development Ready: Neovim with extensive plugin ecosystem

📂 Project Structure

dotfiles/
├── mac/                 # macOS configs — stow from here (target: ~)
│   ├── aerospace/       # Aerospace tiling window manager
│   ├── borders/         # JankyBorders window border configuration
│   ├── ghostty/         # Modern terminal emulator configuration
│   ├── hammerspoon/     # Focus-follows-mouse automation
│   ├── herdr/           # AI-agent terminal multiplexer (alt tmux-style config)
│   ├── kanata/          # Advanced keyboard remapper with home row mods
│   ├── karabiner/       # Keyboard remapping and shortcuts
│   ├── macos/           # Brewfile + setup.sh provisioning
│   ├── scripts/         # Helper + validation scripts
│   ├── sketchybar/      # macOS menu bar replacement
│   ├── starship/        # Cross-shell prompt themes
│   ├── tmux/            # Terminal multiplexer configuration
│   ├── zsh/             # Z shell configuration and plugins
│   └── bootstrap.sh     # macOS provisioning entry point
├── linux/               # Linux (Omarchy/Hyprland) configs — stow from here (target: /home/cyperx)
│   ├── hypr/            # Hyprland window manager
│   ├── waybar/          # Status bar
│   ├── walker/          # Application launcher
│   ├── terminals/       # Terminal emulator configs
│   ├── kanata/          # Keyboard remapper (config.kbd)
│   ├── dev-tools/       # btop, fastfetch, git, lazygit, starship
│   ├── omarchy-user/    # Omarchy user layer
│   ├── tmux/, zsh/, scripts/
│   └── bootstrap.sh     # Linux provisioning entry point
└── docs/                # Shared documentation

Note: Neovim configuration is a separate repository at github.com/cyperx84/nvim — clone directly to ~/.config/nvim

🛠️ Components Overview

👻 Ghostty - Terminal Emulator

Modern GPU-accelerated terminal with extensive customization:

Font: MonaspiceNe Nerd Font family with ligatures
Theme: Monokai Remastered with transparency and blur effects
Features: GPU-accelerated rendering with blur effects
Shortcuts: Global quick terminal toggle (cmd+/)

Key Features:

Font ligatures and stylistic sets (ss01-ss04, liga)
Background blur and transparency effects
macOS-specific optimizations
Secure input handling

🦾 Kanata - Advanced Keyboard Remapper (Active)

Sophisticated keyboard remapping with home row modifiers:

Caps Lock: Escape on tap, Ctrl on hold
Home Row Mods: Hold a/s/d/f/j/k/l/; for modifiers (Cmd/Alt/Shift/Ctrl)
Right Shift: Backspace
Tab: Hyper key (Cmd+Alt+Shift+Ctrl) on hold
Apostrophe ('): ' on tap, Numbers layer on hold
Forward slash (/): Regular / key (no layer)
Right Cmd: Toggle home row mods on/off (tap to switch base↔vanilla layers)
Timing: 200ms tap, 230ms hold thresholds
Binary: /opt/homebrew/bin/kanata (Homebrew symlink)
Auto-start: LaunchDaemon with 5s startup delay via bash wrapper
TCC Permissions: Uses Homebrew symlink so permissions survive brew upgrade
Status: ✅ Active (PRIMARY)

⛓️‍💥 Karabiner-Elements - Keyboard Remapping (Unconfigured)

Installed but currently unused:

Status: ⚠️ simple_modifications is empty
Kanata is the primary keyboard remapper

🚀 Aerospace - Tiling Window Manager (PRIMARY)

macOS tiling window manager with native keybindings:

Configuration: ~/.config/aerospace/aerospace.toml (TOML format)
Auto-start: Launches at login automatically
SketchyBar Integration: Direct workspace callbacks for seamless integration
Padding: 52px top padding for SketchyBar, 20px inner gaps

Key Features:

Native window management without external dependencies
Smart resize adapts to window position
Workspace navigation: cmd+j/k/l for workspaces 1-3
Window focus: shift+ctrl+hjkl
Window movement: shift+ctrl+alt+hjkl
Toggle fullscreen: shift+ctrl+w
Service mode: shift+alt+cmd+r for advanced operations

🔲 JankyBorders - Window Borders

Lightweight window border system for visual clarity:

Active Window: Bright green border (0xff00ff00)
Inactive Windows: Muted gray border (0xff494d64)
Style: Rounded corners, 5px width
Config: ~/.config/borders/bordersrc
Auto-start: Via Aerospace after-startup-command

📊 SketchyBar - Menu Bar Replacement

Elegant and customizable macOS menu bar:

Appearance: Top position, 40px height, blur effects
Font: MonaspiceRn Nerd Font
Modules: Spaces, front app, clock, volume, battery
Integration: Aerospace workspace indicators with instant updates

🪟 Tmux - Terminal Multiplexer

Feature-rich terminal session management:

Prefix: Ctrl+A (instead of default Ctrl+B)
Theme: Catppuccin Mocha with custom status line
Navigation: Vim-style pane navigation (hjkl)
Plugins: 10+ plugins for enhanced functionality

Key Plugins:

tmux-sessionx - Smart session management
tmux-floax - Floating terminal windows
vim-tmux-navigator - Seamless Vim integration
tmux-resurrect + tmux-continuum - Session persistence

🚀 Starship - Cross-Shell Prompt

Highly customizable prompt with multiple themes:

Active Theme: Gruvbox Dark Neon
Available Themes: 5 different configurations
Features: Git integration, language detection, performance metrics
Style: Powerline-inspired with custom symbols

🦪 Zsh - Z Shell

Modern shell with extensive enhancements:

Syntax Highlighting: Fast syntax highlighting
Autosuggestions: Intelligent command completion
FZF Integration: Fuzzy finding for files, commands, and history
Aliases: 50+ productivity aliases for Git, Docker, K8s

Key Features:

Custom FZF functions for navigation (fcd, fv, f)
Yazi file manager integration
UV Python environment management
Extensive Git, Docker, and Kubernetes aliases

👾 Neovim - Text Editor

A powerful, modern Neovim setup based on kickstart.nvim with extensive customization. Separate repository at github.com/cyperx84/nvim — clone to ~/.config/nvim.

Quick Facts:

37 Plugin configuration files
100+ Keybindings organized by function
4 LSP Servers configured (C/C++, Python, Rust, Lua)
4 AI Integrations (Claude, CodeCompanion, Copilot, SuperMaven)
40+ Treesitter Languages for syntax highlighting

Key Features:

AI-assisted development with Claude Code and CodeCompanion
Obsidian integration for knowledge management
Advanced git workflow (Neogit, Gitsigns)
DAP debugging with UI
Multiple file explorers (Mini.files, Oil, Yazi)
Tokyo Night theme with transparency

Complete Documentation: See nvim repository for full details, keybindings, and setup instructions.

🔧 Installation

Prerequisites

First, ensure you have Homebrew installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Essential Dependencies

Core Applications (Casks)

# Terminal & Input
brew install --cask ghostty                 # Modern GPU-accelerated terminal
brew install --cask karabiner-elements      # Advanced keyboard remapping

# Fonts
brew install --cask font-monaspace         # MonaspiceNe Nerd Font family
brew install --cask font-meslo-lg-nerd-font # MesloLGS Nerd Font

System & Window Management

brew install --cask nikitabobko/tap/aerospace  # Aerospace tiling window manager
brew tap FelixKratz/formulae && brew install borders  # JankyBorders window borders
brew install sketchybar                     # Menu bar replacement
brew install stow                           # Configuration management

Shell & Terminal Enhancement

brew install starship                       # Cross-shell prompt
brew install tmux                           # Terminal multiplexer
brew install zsh-fast-syntax-highlighting  # Shell syntax highlighting
brew install zsh-autosuggestions           # Shell autosuggestions
brew install fzf                           # Fuzzy finder
brew install fd                            # Modern 'find' replacement
brew install bat                           # Modern 'cat' with syntax highlighting
brew install eza                           # Modern 'ls' replacement
brew install zoxide                        # Smart directory jumper
brew install ripgrep                       # Fast text search

Development Tools

brew install nvim                          # Neovim text editor
brew install git                           # Version control
brew install gh                            # GitHub CLI
brew install yazi                          # Terminal file manager
brew install sesh                          # Session management

System Utilities

brew install jq                            # JSON processor
brew install wget                          # File downloader
brew install curl                          # Data transfer tool

# Temperature monitoring (required for M4 Macs)
brew tap narugit/tap && brew install narugit/tap/smctemp

Optional Tools

# Programming Languages
brew install uv                            # Python package manager
brew install node                          # Node.js runtime
brew install python                        # Python interpreter

# Kubernetes (if needed)
brew install kubectl                       # Kubernetes CLI
brew install kubectx                       # Kubernetes context switcher
brew install kubens                        # Kubernetes namespace switcher

# Additional Utilities
brew install docker                        # Containerization
brew install switchaudio-osx              # Audio source switcher

Quick Install Script

For convenience, you can install all essential dependencies at once:

# Essential packages only
brew install --cask ghostty karabiner-elements font-monaspace font-meslo-lg-nerd-font nikitabobko/tap/aerospace
brew tap FelixKratz/formulae && brew install borders
brew tap narugit/tap && brew install narugit/tap/smctemp  # M4 temperature monitoring
brew install sketchybar stow starship tmux herdr zsh-fast-syntax-highlighting zsh-autosuggestions fzf fd bat eza zoxide ripgrep nvim git gh yazi sesh jq wget curl

# Optional additions
brew install uv node python kubectl kubectx kubens docker switchaudio-osx kanata

Setup Instructions

Clone the repository:

git clone https://github.com/cyperx84/dotfiles.git ~/dotfiles
cd ~/dotfiles

Run the bootstrap script (recommended — installs Homebrew, all Brewfile apps/casks/fonts, stows every config, sets up TPM and the Kanata daemon):
```
# macOS
~/dotfiles/mac/bootstrap.sh

# Linux (Omarchy)
~/dotfiles/linux/bootstrap.sh
```
Or stow manually from the platform subdirectory if you only want the symlinks:
```
cd ~/dotfiles/mac
stow zsh tmux ghostty aerospace borders sketchybar kanata karabiner sesh starship hammerspoon
```

Start services:

# Start Aerospace (or it will auto-start on login)
open -a AeroSpace

# Start JankyBorders (auto-starts with Aerospace, but manual start if needed)
borders &

# Start SketchyBar
brew services start sketchybar

# Restart shell to load Zsh config
exec zsh

# Install Neovim plugins (on first launch)
nvim  # Wait for plugins to download (~30-60 seconds)

Manual macOS steps (cannot be scripted — Apple security / TCC):

These are the pieces bootstrap.sh can't do for you on a fresh machine:
- Karabiner DriverKit VirtualHIDDevice — Kanata's keyboard remapping will not work without it, and it is not a Homebrew cask. Install the pinned driver (Kanata 1.11 is incompatible with DriverKit v7 — use 6.6.0):
```
# Download + install the v6.6.0 .pkg from the Karabiner releases:
#   https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/releases
# then activate it:
sudo /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate
```
- Input Monitoring — grant it to kanata in System Settings → Privacy & Security → Input Monitoring (the remaps stay dead until you do).
- Accessibility — grant it to AeroSpace and Hammerspoon in System Settings → Privacy & Security → Accessibility.
- Ghostty — set as the default terminal if desired.
See the provision-mac-twin skill for the full fresh-Mac walkthrough, including the Homebrew 6.x / Kanata / TCC gotchas.

📦 Neovim Configuration

Neovim is a standalone repository at github.com/cyperx84/nvim — it is not a submodule of this dotfiles repo.

Installation

# Clone the nvim configuration directly
git clone https://github.com/cyperx84/nvim.git ~/.config/nvim

# Launch Neovim (plugins auto-install on first run)
nvim

Making Changes

# Make changes directly in the nvim repo
cd ~/.config/nvim
git add . && git commit -m "Your change"
git push

No submodule pointer updates needed — the repos are independent.

⚙️ Customization

Keyboard Remapping

Kanata is the active keyboard remapper with home row mods:

Kanata (Active):

Binary: /opt/homebrew/bin/kanata (Homebrew symlink, TCC permissions survive brew upgrade)
LaunchDaemon: Uses bash wrapper with 5s startup delay to ensure Karabiner VirtualHID is ready

# Check status
sudo launchctl print system/com.example.kanata

# Restart after config changes
sudo launchctl kickstart -k system/com.example.kanata

# View config
cat ~/.config/kanata/kanata.kbd

# Verify binary path
ls -la /opt/homebrew/bin/kanata

To switch to Karabiner-Elements:

# Disable Kanata
sudo launchctl bootout system /Library/LaunchDaemons/com.example.kanata.plist

# Configure Karabiner-Elements via its GUI
# Add remappings to simple_modifications

Starship Themes

Switch between different prompt themes by modifying ~/.zshrc:

export STARSHIP_CONFIG=~/.config/starship/starship-gruvbox-dark-neon.toml
# export STARSHIP_CONFIG=~/.config/starship/starship-gruvbox-rainbow.toml
# export STARSHIP_CONFIG=~/.config/starship/starship-jetpack.toml

Tmux Customization

Modify plugin settings in .tmux.conf:

# Float window settings
set -g @floax-width '80%'
set -g @floax-height '80%'
set -g @floax-bind 'p'

🎯 Quick Reference

Most Used Commands

# Session Management
sd                    # Fuzzy connect to session (sesh + fzf)
Alt+s                 # Quick session selector (zsh keybind)
sesh-dashboard        # Comprehensive session overview
ta                    # Attach to tmux

# File Operations
fcd                   # Fuzzy directory navigation
fv                    # Fuzzy file selection + edit
f                     # Yazi file manager with cd
ls                    # Enhanced listing (eza)

# Git Workflow
gs                    # Git status
gc "message"          # Quick commit
gp                    # Push current branch
glog                  # Enhanced git log

# Development
n                     # Open Neovim
conf                  # Edit dotfiles
no                    # Open notes (Obsidian)

Essential Keybinds

# Window Management (Aerospace)
cmd+ctrl+jkl         # Switch workspaces 1-3
shift+ctrl+hjkl      # Focus windows
shift+ctrl+w         # Toggle fullscreen

# Tmux (Prefix: Ctrl+A)
C-a T                # Session switcher
C-a hjkl             # Navigate panes
C-a sv               # Split panes

# Neovim
<leader>sf           # Find files (telescope)
<leader>gg           # Git interface (neogit)
<leader>e            # File manager (mini.files)
jk                   # Exit insert mode

📖 Complete Reference: See Keybinds Documentation for full listings

Validation & Maintenance

# System Health Checks
sesh list                                 # Check sesh sessions (manual)
~/.config/sketchybar/test_sketchybar.sh   # Test SketchyBar plugins

# Service Management
killall AeroSpace && open -a AeroSpace    # Restart window manager
killall borders && borders &              # Restart window borders
sketchybar --reload                       # Reload menu bar
exec zsh                                  # Reload shell config

🔧 Troubleshooting: See Maintenance Guide for detailed procedures

🔍 File Highlights

Configuration Files

ghostty/config - Terminal appearance and behavior
karabiner/karabiner.json - Simple keyboard remapping rules
kanata/kanata.kbd - Advanced keyboard remapping with home row mods
aerospace/aerospace.toml - Aerospace window manager
borders/bordersrc - JankyBorders window borders
tmux/.tmux.conf - Terminal multiplexer setup
zsh/.zshrc - Shell configuration and aliases

Special Features

Aerospace: Tiling window management with tiles/accordion layouts
JankyBorders: Visual window borders (green active, gray inactive)
SketchyBar Plugins: 40 custom status bar plugins in sketchybar/plugins/
Starship Themes: 5 different prompt configurations
Tmux Plugins: Auto-installing plugin manager with 10 plugins
Neovim: 37 plugin configuration files (separate repo at github.com/cyperx84/nvim)
Local LLM: Gemma 4 on MLX serving OpenClaw/Hermes (see docs/MLX_GEMMA_SETUP.md)

🤝 Contributing

Feel free to fork this repository and adapt it to your needs. If you have improvements or suggestions:

Fork the repository
Create a feature branch
Submit a pull request

📝 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

nvim-lua/kickstart.nvim - Neovim configuration base
Catppuccin - Beautiful color schemes
The amazing macOS community for tool development

This dotfiles setup represents years of refinement for optimal productivity and aesthetics on macOS.

Author

cyperx - GitHub Profile

For issues or contributions, visit the dotfiles repository.

Name		Name	Last commit message	Last commit date
Latest commit History 376 Commits
.claude		.claude
docs		docs
linux		linux
mac		mac
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

👾 cyperx's Dotfiles

📚 Documentation Hub

🌟 Features

📂 Project Structure

🛠️ Components Overview

👻 Ghostty - Terminal Emulator

🦾 Kanata - Advanced Keyboard Remapper (Active)

⛓️‍💥 Karabiner-Elements - Keyboard Remapping (Unconfigured)

🚀 Aerospace - Tiling Window Manager (PRIMARY)

🔲 JankyBorders - Window Borders

📊 SketchyBar - Menu Bar Replacement

🪟 Tmux - Terminal Multiplexer

🚀 Starship - Cross-Shell Prompt

🦪 Zsh - Z Shell

👾 Neovim - Text Editor

🔧 Installation

Prerequisites

Essential Dependencies

Core Applications (Casks)

System & Window Management

Shell & Terminal Enhancement

Development Tools

System Utilities

Optional Tools

Quick Install Script

Setup Instructions

📦 Neovim Configuration

Installation

Making Changes

⚙️ Customization

Keyboard Remapping

Starship Themes

Tmux Customization

🎯 Quick Reference

Most Used Commands

Essential Keybinds

Validation & Maintenance

🔍 File Highlights

Configuration Files

Special Features

🤝 Contributing

📝 License

🙏 Acknowledgments

Author

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages