CLAUDE.md I am using for Omarchy. Place it in ~/.coinfig and run Claude code from there. https://x.com/jorgemanru/status/1968221757866905887

CLAUDE.md

Claude Linux System Configuration Assistant

System Context

I am running a Linux system and need help with configuration, setup, and administration tasks. Please assist me following Linux best practices and respecting system defaults.

Current System Information

• Distribution: Omarchy Linux (Arch-based)
• Window Manager: Hyprland
• Home Directory: /home/jorge
• Working Directory: Check with pwd before making assumptions

Core Principles

CRITICAL RULES:

1. Push file changes via chezmoi after modifications
2. NEVER modify system files without explicit permission
3. Respect the separation between system defaults and user customization
4. Check for existing configurations before creating new ones
5. Follow the principle of least privilege - Use sudo only when necessary
6. Document all changes made to the system

Configuration Hierarchy (DO NOT VIOLATE):

1. User-specific configs in ~/.config/ (preferred)
2. User home directory dotfiles ~/.* (legacy)
3. System-wide configs in /etc/ (requires sudo, avoid when possible)
4. Default configs in /usr/share/ (NEVER modify)

Best Practices

Before Making Any Changes:

1. Investigate current state:

   # Check if configuration already exists
   ls -la ~/.config/[application]/
   find ~ -name "*[application]*" -type f 2>/dev/null
   
   # Look for example/default files
   find /usr/share -name "*[application]*" -type f 2>/dev/null
   find /etc -name "*[application]*" -type f 2>/dev/null

2. Test changes:

   • Make incremental changes
   • Test after each change
   • Have a rollback plan

Common Tasks Approach

Installing Software:

1. Check if available in distribution's package manager first
2. Use AUR (for Arch-based) as second option
3. Manual installation as last resort
4. Document installation method for future updates

Service Management:

# System services (requires sudo)
systemctl status/start/stop/enable/disable [service]

# User services (no sudo needed)
systemctl --user status/start/stop/enable/disable [service]

Configuration Files:

1. Use proper format (YAML, TOML, JSON, INI) as expected by application
2. Include comments explaining customizations
3. Keep original structure intact
4. Use includes/sources when possible instead of modifying main files

Environment Variables:

# Session-wide (preferred)
~/.config/environment.d/*.conf

# Shell-specific
~/.bashrc or ~/.zshrc

# System-wide (avoid)
/etc/environment

Task Request Format

When asking for help, I'll provide:

• What I want to accomplish
• Any specific constraints or preferences
• What I've already tried (if applicable)

Example requests:

• "Help me configure [application] properly"
• "I need to set up [service] to start automatically"
• "Show me how to install and configure [tool]"
• "Debug why [application] isn't working"
• "Optimize [system component] for better performance"

Safety Guidelines

Always:

• Check file permissions after creating/modifying configs
• Verify syntax before applying configuration changes
• Keep a session open when modifying network/SSH configs
• Test commands with echo or --dry-run first when available
• Use version control for important configs

Never:

• Run commands with sudo unless absolutely necessary
• Pipe curl/wget directly to bash without reviewing
• Modify files in /usr/ or /boot/ without explicit need
• Delete files without understanding their purpose
• Disable security features without good reason

Debugging Approach

When something isn't working:

1. Check logs:

   journalctl -xe                    # System logs
   journalctl --user -xe             # User logs
   journalctl -u [service] -f        # Follow specific service

2. Verify permissions:

   ls -la [file]
   namei -l [path]

3. Check processes:

   ps aux | grep [process]
   systemctl status [service]

4. Test configuration:

   [application] --config-test
   [application] -t

System Information Commands

# Distribution info
cat /etc/os-release
uname -a

# Hardware info
lscpu
lsmem
lsblk
lspci
lsusb

# Network info
ip addr
ss -tulpn
nmcli device status

# Disk usage
df -h
du -sh /*

# Running services
systemctl list-units --state=running
systemctl --user list-units --state=running

# Package management (Arch-based)
pacman -Q               # List installed packages
pacman -Qs [search]     # Search installed packages
pacman -Ss [search]     # Search available packages

Performance and Resource Management

Monitor resources:

htop or btop           # Interactive process viewer
iostat -x 1            # I/O statistics
vmstat 1               # Virtual memory statistics

Dotfiles Management with Chezmoi

My dotfiles are managed with chezmoi and backed up to GitHub at jorgemanrubia/dotfiles.

After modifying configuration files

Always push changes using chezmoi after file modifications:

chezmoi re-add && cd $(chezmoi source-path) && git add . && git commit -m "Your commit message" && git push

This applies to:

• Editing configuration files
• Creating new configuration files
• Deleting configuration files
• Modifying CLAUDE.md itself
• Any file operation in tracked directories

Replace "Your commit message" with a description of your changes.

Documentation

After making changes:

1. Document what was changed and why
2. Note any dependencies or requirements
3. Include rollback procedures
4. Save relevant commands for future reference
5. Commit configuration changes to dotfiles repo if applicable

Final Notes

• Prefer simple solutions over complex ones
• Use native tools when possible
• Follow distribution-specific conventions
• Test in a safe environment when possible
• Ask for clarification if requirements are unclear

Please help me with my Linux system configuration and administration tasks following these guidelines.