omnixy/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This repository contains Omarchy NixOS, a declarative system configuration that transforms NixOS into a beautiful, modern development environment based on Hyprland. Unlike the original Arch-based Omarchy, this version uses Nix's declarative configuration management for reproducible systems.

Key Commands

System Management

# Rebuild system configuration
sudo nixos-rebuild switch --flake /etc/nixos#omarchy
omarchy-rebuild  # Convenience wrapper

# Update system and flake inputs
omarchy update

# Clean and optimize Nix store
omarchy clean

# Search for packages
omarchy search <package-name>

Development Workflows

# Test configuration changes
nixos-rebuild build --flake .#omarchy  # Build without switching

# Enter development shell
nix develop  # Uses flake.nix devShell
nix develop .#python  # Language-specific shell

# Format Nix code
nixpkgs-fmt *.nix
alejandra *.nix  # Alternative formatter

# Check Nix code
statix check .  # Static analysis
deadnix .       # Dead code elimination

Theme Development

# Available themes in modules/themes/
ls modules/themes/

# Test theme switch
omarchy theme tokyo-night

# Create new theme
cp modules/themes/tokyo-night.nix modules/themes/my-theme.nix
# Edit color values and application configs

Architecture

Flake Structure

• flake.nix - Main flake definition with inputs and outputs
• configuration.nix - Main NixOS configuration entry point
• home.nix - Home-manager configuration for user environment

Module System

The configuration is split into focused modules:

• modules/core.nix - Base system settings and Omarchy options
• modules/packages.nix - Package collections with feature flags
• modules/development.nix - Development tools and environments
• modules/desktop/hyprland.nix - Hyprland compositor configuration
• modules/services.nix - System services and daemons
• modules/users.nix - User account management
• modules/themes/ - Theme-specific configurations

Configuration Management

1. Declarative - Everything defined in Nix expressions
2. Modular - Features can be enabled/disabled via options
3. Reproducible - Same configuration produces identical systems
4. Version Controlled - All changes tracked in git

Theme System

• Each theme is a complete Nix module in modules/themes/
• Themes configure: terminals, editors, GTK, Qt, desktop components
• Theme switching updates configuration.nix and rebuilds system
• Colors defined as variables for consistency

Package Management

• System packages in modules/packages.nix with feature categories
• User packages in home.nix via home-manager
• Development environments via flake devShells
• Custom packages in packages/ directory

Development Guidelines

Adding Packages

1. System packages: Add to modules/packages.nix in appropriate category
2. User packages: Add to home.nix home.packages
3. Development only: Add to devShell in flake.nix
4. Always rebuild/test: nixos-rebuild build --flake .#omarchy

Creating Modules

1. Follow NixOS module structure with options and config sections
2. Use lib.mkEnableOption and lib.mkOption for configuration
3. Implement feature flags for optional functionality
4. Document options and provide sensible defaults

Theme Development

1. Copy existing theme as template
2. Define color palette as environment variables
3. Configure all supported applications consistently
4. Test theme switching functionality

Custom Packages

1. Create derivations in packages/ directory
2. Use pkgs.writeShellScriptBin for simple scripts
3. Add to flake outputs for external use
4. Follow Nix packaging guidelines

Flake Management

• Pin inputs for stability: nix flake update --commit-lock-file
• Use follows for input deduplication
• Provide multiple devShells for different workflows
• Export packages and apps for external consumption

Testing Changes

• Build configuration: nixos-rebuild build --flake .#omarchy
• Test in VM: nixos-rebuild build-vm --flake .#omarchy
• Check evaluation: nix flake check
• Format code: nixpkgs-fmt .

Home Manager Integration

• User-specific configuration in home.nix
• Theme integration via home-manager modules
• Dotfile management through Nix expressions
• Service management via systemd user units

Common Tasks

Adding New Service

1. Define in modules/services.nix
2. Use systemd service configuration
3. Add necessary packages
4. Configure firewalls/permissions as needed

Hardware Support

1. Add hardware-specific modules in modules/hardware/
2. Use conditional configuration based on hardware detection
3. Include necessary firmware and drivers
4. Test on target hardware

Debugging Issues

• Check system logs: journalctl -xe
• Nix build logs: nix log /nix/store/...
• Configuration evaluation: nix show-config
• Module option documentation: man configuration.nix