dougburks/ohmydebn/ohmydebn-skill

OhMyDebn Skill

Manage OhMyDebn Linux systems - a debonair Linux platform that combines the stability of a Debian-based distro (Debian, Ubuntu, Mint and others), the ease of use of the Cinnamon desktop, and the beauty of Omarchy.

When This Skill MUST Be Used

ALWAYS invoke this skill when the user's request involves ANY of these:

• Editing ANY file in ~/.config/cinnamon/ (desklets, applets, extensions, panels, etc.)
• Editing ANY file in ~/.config/nemo/, ~/.config/gtk-3.0/, ~/.config/gtk-4.0/
• Editing terminal configs (alacritty, terminator, gnome-terminal, mate-terminal, xfce4-terminal)
• Editing ANY file in ~/.config/ohmydebn/
• Editing shell configuration files (~/.zshrc, ~/.config/zsh/, etc.)
• Window management, workspace behavior, panel configuration
• Desktop effects, animations, themes, wallpapers, fonts, appearance changes
• Any ohmydebn-* command (theme, pkg, reset-config, update, version)
• Screenshots, screen recording, power management, screensaver, startup applications
• App launcher / window switcher / theme picker configuration and theming

If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.

Critical Safety Rules

NEVER modify anything in `/usr/share/ohmydebn/` - but READING is safe and encouraged.

This directory contains OhMyDebn's source files managed by the ohmydebn deb package. Any changes will be lost on the next ohmydebn-update or package upgrade, conflict with upstream, and break the system's package management.

/usr/share/ohmydebn/          # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/                      # Source scripts (added to PATH)
├── config/                   # Default config templates
└── install/                  # Installation scripts

Reading these directories is SAFE and useful - do it freely to:

• Understand how ohmydebn commands work: cat $(which ohmydebn-theme-set)
• See default Cinnamon settings before customizing: cat /usr/share/ohmydebn/install/config/cinnamon.sh (Cinnamon settings are applied via gsettings, not a flat config file)
• Check stock theme files (the OhMyDebn theme and the original Omarchy themes) to copy for customization: ls /usr/share/ohmydebn-themes/

Always use these safe locations instead:

• ~/.config/ - User configuration (safe to edit)
• ~/.config/ohmydebn/themes/<custom-name>/ - Custom themes (a directory, or a link to one kept elsewhere)

OhMyDebn Features:

• Desktop Effects: Enabled by default, disable via System Settings → Effects
• AI assistants: optional installs from Apps > AI (OpenCode and OpenCode Desktop, Claude Code, Codex, Grok Build, Crush, Pi, Oh My Pi, T3 Code and more). Super + A opens the default one, chosen in Setup > Defaults > Agent (OpenCode until changed). Super + the key left of 1 (ohmydebn-console) toggles a drop-down console running the default terminal assistant (or a shell), which keeps running while hidden. Installed ones are kept current via ohmydebn-update
• Apps Menu: GTK app launcher (ohmydebn-menu-picker --apps), Super + R or OhMyDebn Menu → Apps → Other Apps

System Architecture

OhMyDebn is built on:

Command Discovery

OhMyDebn provides commands following ohmydebn-<category>-<action> pattern.

# List all ohmydebn commands
ls /usr/share/ohmydebn/bin/ | grep ohmydebn-
 
# Find commands by category
ls /usr/share/ohmydebn/bin/ | grep ohmydebn-theme
ls /usr/share/ohmydebn/bin/ | grep ohmydebn-pkg
 
# Read a command's source to understand it
cat $(which ohmydebn-theme-set)

Command Categories

Configuration Locations

Cinnamon Desktop Environment

~/.config/cinnamon/
└── spices/                # Per-instance configs for applets, desklets and extensions (e.g. spices/gTile@OhMyDebn/)

Core Cinnamon settings (panel layout, which applets are enabled, effects, keybindings, window management, etc.) are not stored in a flat file — they live in the dconf database under the org.cinnamon schemas. Read/write them with gsettings get|set org.cinnamon ... or browse everything with dconf-editor / dconf dump /org/cinnamon/.

Key behaviors:

• Cinnamon auto-reloads most settings changes (no restart needed)
• Use Ctrl + Alt + Escape to restart Cinnamon desktop
• Use ohmydebn-reset-config to reset OhMyDebn's app config files (terminal, shell, editor and the like) to defaults; desktop settings are left alone

Nemo File Manager

• Preferences: dconf, under org.nemo (e.g. gsettings get org.nemo.preferences default-folder-viewer)
• Bookmarks: ~/.config/gtk-3.0/bookmarks
• Custom context menu actions: ~/.local/share/nemo/actions/

Nemo picks up `gsettings` changes immediately.

GTK Theme Configuration

~/.config/gtk-3.0/
├── settings.ini          # GTK3 settings
└── bookmarks             # GTK bookmarks
 
~/.config/gtk-4.0/
└── settings.ini          # GTK4 settings

GTK applications reload themes automatically.

Alacritty (Default Terminal)

~/.config/alacritty/alacritty.toml    # Main configuration

The default terminal is Alacritty with:

• Caskaydia Nerd Fonts
• Zsh shell with Oh My Zsh
• Starship shell prompt
• Zoxide for smart cd command
• eza for beautiful directory listings
• bat for cat with syntax highlighting

Restart terminal applications by closing and reopening the window or using the application's restart functionality.

Other Terminals

~/.config/terminator/config
~/.config/xfce4/terminal/
└── terminalrc            # Configuration

gnome-terminal and mate-terminal keep their settings in dconf, not in files: dconf dump /org/gnome/terminal/ and dconf dump /org/mate/terminal/.

Other Configs

Safe Customization Patterns

Pattern 1: Edit User Config Directly

For simple changes, edit files in ~/.config/:

# 1. Read current config
cat ~/.config/alacritty/alacritty.toml
 
# 2. Backup before changes
cp ~/.config/alacritty/alacritty.toml ~/.config/alacritty/alacritty.toml.bak.$(date +%s)
 
# 3. Make changes with Edit tool
 
# 4. Apply changes
# - Cinnamon: settings live in dconf (org.cinnamon schemas) — use `gsettings set`, auto-reloads, no flat file to edit
# - Terminals: restart by closing and reopening window

Pattern 2: Make a new theme

1. Create a directory under ~/.config/ohmydebn/themes.
2. See how existing themes are done via:

• /usr/share/ohmydebn-themes/ohmydebn/ for the native OhMyDebn theme
• /usr/share/ohmydebn-themes/tokyo-night/ for original Omarchy themes (interpreted for Cinnamon)

1. Add a colors.toml (or alacritty.toml) to the theme directory. It is required: ohmydebn-theme-set refuses a theme without one.
2. Download a matching background (or several) from the internet and put them in ~/.config/ohmydebn/themes/[name-of-new-theme]/backgrounds/
3. When done with the theme, run ohmydebn-theme-set "Name of new theme"

Pattern 3: Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING

When customizations go wrong:

# Reset all configured apps to defaults (creates backup automatically)
ohmydebn-reset-config
 
# The reset-config command:
# 1. Renames ~/.config/{alacritty,bat,btop,cava,nvim,starship.toml},
#    ~/.oh-my-zsh (your own Oh My Zsh plugins and themes) and ~/.zshrc to
#    *-backup-<timestamp>
# 2. Clears only the state markers of the steps that write those files
# 3. Re-runs OhMyDebn's configuration (ohmydebn.sh, without the system upgrade), which writes fresh defaults
# 4. Reapplies the current theme (keeping the background)
# Desktop settings, panel, extensions, keybindings, theme, firewall and
# default apps are not changed.

Common Tasks

Themes

ohmydebn-theme-list              # Show available themes
ohmydebn-theme-current           # Show current theme
ohmydebn-theme-set <name>        # Apply theme ("Tokyo Night" and "tokyo-night" both work)
ohmydebn-theme-next              # Cycle to next theme
ohmydebn-theme-bg-next           # Cycle wallpaper
ohmydebn-theme-install <url>     # Install from git repo

Theme Management:

• GUI: OhMyDebn Menu → Appearance → Theme or hotkey Ctrl + Super + T
• Background switching: OhMyDebn Menu → Appearance → Background or Ctrl + Super + B opens the theme carousel (Up/Down picks a background), or run ohmydebn-theme-bg-next. Each theme remembers its last background
• Build custom themes: Ctrl + Shift + A (Aether theme builder)
• Browse more themes: press B in the theme carousel (Ctrl + Super + T)
• Theme intros: switching themes and logging in play a short intro that fades into the background: the background itself at twilight with the light arriving and a shimmer, drawn live, or for some Omarchy backgrounds Omarchy's own clip. Turn them off or on with ohmydebn-theme-intro-toggle (Appearance > Theme Intros). A user's own background in ~/.config/ohmydebn/backgrounds/<theme>/ can have its own clip at intros/<same name>.webm (WebM/VP9; an .mp4 may not play, and a clip that can't play falls back to the drawn intro)

Keybindings

Terminology: a hotkey is the key combination you press (the docs page at ohmydebn.org/hotkeys lists them); a keybinding is the configuration that ties a key to an action. Menus, commands and files say keybinding.