Hyprland Desktop Configuration

NeoVim Configurations

Hardware Specs

Running on a ThinkPad X1 Carbon 7th Gen with Intel i7-8565U (8 cores @ 4.6GHz), 16GB RAM, and Intel UHD Graphics 620 at 2560x1440 resolution.

A complete Wayland desktop environment configuration featuring Hyprland window manager, optimized for development workflows on Arch Linux.

Features

README.md

• Modern Wayland Desktop: Full Hyprland setup with smooth animations and gestures
• Development-Ready: Comprehensive Neovim configuration with LSP, debugging, and Git integration
• Theme System: Multiple Catppuccin and Gruvbox theme variants with dynamic switching
• Professional Workflow: Integrated terminal, launcher, notifications, and system monitoring
• GNU Stow Management: Clean, organized dotfile deployment system

Components

Component	Tool	Description
Window Manager	Hyprland	Tiling window manager with animations
Status Bar	Waybar	Customizable bar with system monitoring
Terminal	Kitty	GPU-accelerated terminal with transparency
Editor	Neovim	Full IDE setup with Lazy.nvim plugin manager
Launcher	Wofi	Application launcher and menu system
Notifications	SwayNC	Notification daemon with action center
Lock Screen	Hyprlock	Secure screen locking with blur effects
Idle Management	Hypridle	Automatic screen dimming and locking
Wallpapers	Hyprpaper	Dynamic wallpaper management
Audio	PipeWire	Modern audio server configuration
On-Screen Display	SwayOSD	Volume/brightness overlay indicators
Keyboard Remap	Kanata	Advanced keyboard remapping for Wayland
Shell Prompt	Starship	Cross-shell customizable prompt
AI Coding	OpenCode	AI coding assistant with MCP support

Quick Start

Prerequisites

• Arch Linux (or Arch-based distribution)
• yay AUR helper
• GNU Stow for dotfile management

Installation

1. Clone this repository:

git clone <your-repo-url> ~/.dotfiles
cd ~/.dotfiles

2. Install Neovim environment:

./install-nvim.sh

3. Deploy configurations:

# Deploy all configurations
stow */

# Or deploy specific components
stow hyprland waybar kitty nvim

4. Verify setup:

# Check Neovim health
nvim +checkhealth

# Test Hyprland (logout and select Hyprland session)

Repository Structure

~/.dotfiles/
├── backgrounds/     # Wallpaper collection
├── hyprland/        # Window manager config
├── hyprlock/        # Lock screen settings
├── hyprmocha/       # Catppuccin Mocha theme for Hyprland
├── hyprpaper/       # Wallpaper management
├── kanata/          # Keyboard remapping configuration
├── kitty/           # Terminal configuration
├── nvim/            # Neovim development environment
├── opencode/        # AI coding assistant config
├── pipewire/        # Audio system config
├── polybar/         # Alternative status bar (legacy)
├── rofi/            # Alternative launcher (legacy)
├── scripts/         # System utility scripts
├── starship/        # Shell prompt configuration
├── swayosd/         # On-screen display for volume/brightness
├── systemd/         # User services (battery, reminders)
├── waybar/          # Status bar with themes
├── wlogout/         # Logout menu
├── wofi/            # Application launcher
└── install-nvim.sh  # Neovim setup script

Development Environment

Neovim Configuration

Complete IDE experience powered by modern Neovim plugins:

Core Features:

• Plugin Manager: Lazy.nvim with lazy loading
• LSP Integration: Mason for server management + nvim-lspconfig
• Completion: nvim-cmp with snippet support
• Fuzzy Finding: Telescope for files and live grep
• File Explorer: Neo-tree with Git integration
• Debugging: DAP support for multiple languages
• Git Workflow: LazyGit + Gitsigns + GitGraph visualization
• Custom Cheatsheet: Searchable keybinding reference

Additional Plugins:

• AI Assistant: Avante for AI-powered coding assistance
• Terminal: Toggleterm for integrated terminal
• UI Enhancements: Fine-cmdline, Bufferline, Lualine
• Diagnostics: Tiny-inline-diagnostic for inline error display
• Image Preview: Image.nvim for in-editor image viewing
• Docker: Lazydocker integration
• Markdown: Live preview support

Key Bindings:

• <Space> - Leader key
• <C-p> - Find files (Telescope)
• <leader>fg - Live grep search
• <C-n> - Toggle file explorer
• <leader>ch - Open cheatsheet
• <Tab> / <S-Tab> - Navigate buffers

Language Support

Pre-configured LSP servers for:

• Web: TypeScript, JavaScript, HTML, CSS
• Systems: Lua, Bash, Python
• Markup: Markdown, JSON, YAML

OpenCode Configuration

AI coding assistant with MCP (Model Context Protocol) support.

Setup:

# Deploy configuration
stow opencode

# Install context-mode MCP tool globally
npm install -g context-mode

# Set your Context7 API key (add to ~/.bashrc or ~/.zshrc)
export CONTEXT7_API_KEY="your-api-key-here"

Features:

• Context7 MCP integration for documentation search
• Use use context7 in prompts to search docs

Figma Remote MCP

Figma maintains a client whitelist for their remote MCP and OpenCode is not on it yet (pending approval as of March 2026). A one-time workaround using a patched fork is required to authenticate — the resulting OAuth tokens are cached and picked up by your normal opencode binary automatically.

1. Deploy the config (already includes Figma):

stow opencode

2. One-time OAuth via the workaround fork:

git clone -b mcp-auth-workaround https://github.com/connorads/opencode.git ~/repos/opencode-mcp-auth
cd ~/repos/opencode-mcp-auth
bun install
bun dev mcp auth figma

Browser opens → Figma OAuth → click Allow access. Tokens are cached to ~/.local/share/opencode/mcp-auth.json. Restart OpenCode — done.

Re-auth (if tokens expire): repeat step 2 from ~/repos/opencode-mcp-auth.

Full details and usage: opencode/.opencode/FIGMA-MCP.md Tracking issue: anomalyco/opencode#5636

opencode-anthropic-oauth (Claude Pro/Max OAuth)

Plugin for Anthropic Claude Pro/Max OAuth login — no Claude Code or API key needed. Implements OAuth PKCE flow directly against Anthropic's auth endpoints with auto-refresh.

Install: already included in opencode/.opencode/opencode.json via "plugin": ["opencode-anthropic-oauth"]. OpenCode auto-installs from npm on first launch.

Usage:

1. Run /connect in OpenCode (or oc auth login from CLI)
2. Select Anthropic > Claude Pro/Max
3. Open the link in your browser and authorize
4. Paste the code back into OpenCode
5. Done — all Anthropic models are now available

Upgrade to latest version:

cd ~/.cache/opencode && npm install opencode-anthropic-oauth@latest

Then restart OpenCode.

Source: https://github.com/shahidshabbir-se/opencode-anthropic-oauth

Theming

Available Themes

Catppuccin Variants:

• Mocha (dark)
• Macchiato (dark)
• Frappe (dark)
• Latte (light)

Gruvbox Variants:

• Dark
• Light

Theme Management

# Switch themes using waybar scripts
~/.config/waybar/scripts/theme-switcher.sh


# Themes are automatically applied to:
# - Waybar, Kitty, Hyprland, Wofi, Rofi

Customization

Waybar Modules

Located in waybar/.config/waybar/:

• System Monitoring: CPU temp, memory, battery
• Network: WiFi status and controls
• Audio: Volume control with PipeWire
• Power: Battery with charging status
• Workspaces: Hyprland workspace integration
• Reminders: Markdown-based reminder system with notifications

Reminders Integration

Waybar module that displays reminders from markdown files.

Features:

• Displays reminder count next to clock with color-coded status
• Hover tooltip shows categorized reminders (Overdue, Today, Upcoming)
• Click to open interactive popup for completing reminders
• Cascading notifications at 2h, 1h, 30m, 15m, 5m before reminders
• Systemd timer checks for upcoming reminders every minute

Reminder Format (in ~/Documents/notes/Reminders/*.md):

- [ ] Task description (@YYYY-MM-DD HH:mm)
- [ ] Buy groceries (@2026-01-15 10:00)
- [x] Completed task (@2026-01-08 14:30)

Status Indicators:

Icon	Color	Meaning
󰂚	Gray	No reminders
󰂜	Green	Upcoming reminders
󰂜	Yellow	Reminders today
󰂞	Red (pulsing)	Overdue reminders

Setup:

# Install dependencies
sudo pacman -S yad jq

# Create reminders directory
mkdir -p ~/Documents/notes/Reminders

# Enable notification timer
systemctl --user enable --now reminders-notify.timer

Custom Scripts

Available in scripts/.config/scripts/:

• battery.sh - Battery status reporting
• open-folder-bg.sh - Open folder in background
• power.sh - Power management menu
• rofi-fb-official.sh - Rofi file browser
• screen_record.sh - Screen recording utility
• screenshot.sh - Screenshot capture utility
• wallpaper-switcher.sh - Dynamic wallpaper switching
• whatsong.sh - Current playing song display
• whoami.sh - User information display
• wlogout.sh - Logout menu launcher
• workspace_action.sh - Workspace automation

Waybar Scripts

Available in waybar/.config/waybar/scripts/:

• battery-level.sh - Battery percentage display
• battery-state.sh - Battery charging state
• bluetooth-menu.sh - Bluetooth device management
• brightness-control.sh - Screen brightness control
• cpu-temp.sh - CPU temperature monitoring
• current-theme.sh - Active theme detection
• mic-status.sh - Microphone mute status
• power-menu.sh - Power options menu
• reminders.sh - Markdown reminders waybar module
• reminders-popup.sh - Interactive reminder completion dialog
• reminders-notify.sh - Reminder notification daemon
• system-update.sh - Package update checker
• theme-switcher.sh - Theme switching utility
• volume-control.sh - Audio volume control
• wifi-menu.sh - WiFi network management
• wifi-status.sh - WiFi connection status

Hyprland Configuration

Located in hyprland/.config/hypr/:

• hyprland.conf - Main configuration file
• keybindings.conf - Keyboard shortcuts (separate file)
• hypridle.conf - Idle timeout and actions
• monitors.conf - Display/monitor settings

Features:

• Animations: Smooth window transitions
• Gestures: Touchpad gesture support
• Keybindings: Optimized for productivity
• Multi-monitor: Dynamic display configuration
• Theme Integration: Sources Catppuccin Mocha colors from hyprmocha/

GRUB Configuration

Edit /etc/default/grub for kernel boot parameters:

# Show systemd logs during boot (remove 'quiet')
GRUB_CMDLINE_LINUX_DEFAULT="loglevel=3"

# Apply changes
sudo grub-mkconfig -o /boot/grub/grub.cfg

System Requirements

Essential Packages

Core System:

hyprland waybar kitty wofi swaync
hyprlock hyprpaper hypridle hyprshot
neovim git curl wget ripgrep fd
swayosd kanata

Development Tools:

nodejs npm python python-pip
lazygit debugpy netcoredbg

Audio/Media:

pipewire pipewire-pulse pipewire-alsa
wl-clipboard cliphist

Optional Dependencies

• Fonts: CaskaydiaCove Nerd Font, Figtree
• Cursors: Catppuccin cursor themes
• Icons: Papirus or similar icon pack
• Reminders: yad, jq (for reminders integration)

Troubleshooting

Common Issues:

1. Stow conflicts: Remove existing dotfiles before stowing
2. Missing dependencies: Run ./install-nvim.sh first
3. LSP not working: Check :Mason in Neovim
4. Audio issues: Verify PipeWire is running
5. Theme not applying: Check waybar script permissions

Debug Commands:

# Check Hyprland logs
journalctl -f -u hyprland

# Verify stow links
stow -n -v */

# Test Neovim health
nvim +checkhealth

Screenshots

---

Installation Guide: For complete system setup, see arch-linux-setup

License: Personal configuration - adapt as needed for your setup