OhMyDebn Skill

Manage OhMyDebn Linux systems - a debonair Linux platform that combines the stability of the Debian distro, 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 next ohmydebn-update or package upgrade
• Cause conflicts with upstream
• Break the system's package management

/usr/share/ohmydebn/          # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/                      # Source scripts (symlinked 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 to copy for customization: ls /usr/share/ohmydebn-themes/
• Check original Omarchy themes: ls /usr/share/ohmydebn-themes/

Always use these safe locations instead:

• ~/.config/ - User configuration (safe to edit)
• ~/.config/ohmydebn/themes/<custom-name>/ - Custom themes (must be real directories)

OhMyDebn Features:

• Desktop Effects: Enabled by default, disable via System Settings → Effects
• AI assistants: optional installs from Apps > AI (OpenCode, Claude Code, Codex, Grok Build, Pi, Oh My Pi, T3 Code and more). Super + A opens the default one, chosen in Setup > Defaults > Agent (OpenCode until changed). Installed ones are kept current via ohmydebn-update
• Apps Menu: GTK app launcher (ohmydebn-menu-picker --apps), Super + R or OhMyDebn Menu → Apps

System Architecture

OhMyDebn is built on:

Component	Purpose	Config Location
Debian 13 or a supported derivative	Base OS	/etc/, ~/.config/
Cinnamon	Desktop environment	~/.config/cinnamon/
Nemo	File manager	~/.config/nemo/
Cinnamon Panel	Taskbar/applets	gsettings (org.cinnamon), applet/desklet instance configs under ~/.config/cinnamon/spices/
GTK3/GTK4	Widget toolkit	~/.config/gtk-3.0/, ~/.config/gtk-4.0/
ohmydebn-menu-picker	App launcher / menu search (GTK, not rofi)	~/.config/ohmydebn/current/picker-colors (theming only)
Alacritty	Default terminal	~/.config/alacritty/
gTile	Advanced window tiling	System Settings → Extensions
Cinnamon Screensaver	Lock screen	gsettings (org.cinnamon.desktop.screensaver); trigger with cinnamon-screensaver-command -l
Cinnamon Notification Daemon	Notifications	System settings

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

Prefix	Purpose	Example
ohmydebn-reset-config	Reset OhMyDebn's app configs to defaults (backs them up first)	ohmydebn-reset-config
ohmydebn-theme-*	Theme management	ohmydebn-theme-set <name>
ohmydebn-pkg-*	Package management	ohmydebn-pkg-install <pkg>
ohmydebn-update-*	System updates	ohmydebn-update

Configuration Locations

Cinnamon Desktop Environment

~/.config/cinnamon/
├── panels/                 # Panel configurations
│   └── panel1/            # Top panel settings (OhMyDebn's default, single panel)
├── applets/               # Applet configurations
├── desklets/              # Desklet configurations
├── extensions/            # Extension configurations
├── spices/                # Spice (extension/applet/desklet) configs
└── background-chooser.log # Background selection logs

Core Cinnamon settings (panels, 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 all configs to defaults

Nemo File Manager

~/.config/nemo/
├── nemo-actions          # Custom context menu actions
├── bookmarks             # Bookmarks
└── nemo_preferences      # File manager preferences

Nemo auto-reloads on config save.

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/gnome-terminal/
├── accels                # Keyboard shortcuts
├── profiles/             # Terminal profiles
└── settings              # General settings
~/.config/mate-terminal/
├── profiles/             # Terminal profiles
└── mate-terminal.rc      # Configuration
~/.config/xfce4/terminal/
└── terminalrc            # Configuration

Other Configs

App	Location
btop	~/.config/btop/btop.conf
fastfetch	~/.config/fastfetch/config.jsonc
lazygit	~/.config/lazygit/config.yml
starship	~/.config/starship.toml
git	~/.config/git/config
zsh	~/.zshrc, ~/.config/zsh/
oh my zsh	~/.oh-my-zsh/
zoxide	~/.config/zoxide/
eza	Configured via shell aliases
bat	~/.config/bat/config
cava	~/.config/cava/config
opencode	~/.config/opencode/
wallpapers	~/.config/ohmydebn/current/theme/backgrounds/ (current theme), ~/.config/ohmydebn/backgrounds/<theme>/ (user overrides)

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)
3. Download a matching background (or several) from the internet and put them in ~/.config/ohmydebn/themes/[name-of-new-theme]
4. 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/{aether,alacritty,bat,btop,cava,nvim,starship.toml},
#    ~/.oh-my-zsh and ~/.zshrc to *-backup-<timestamp>
# 2. Deletes OhMyDebn's state markers (~/.local/state/ohmydebn*)
# 3. Re-runs OhMyDebn's configuration (ohmydebn.sh), which writes fresh defaults

Common Tasks

Themes

ohmydebn-theme-list              # Show available themes
ohmydebn-theme-current           # Show current theme
ohmydebn-theme-set <name>        # Apply theme (use "Tokyo Night" not "tokyo-night")
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 → Style → Theme or hotkey Ctrl + Super + T
• Background switching: Ctrl + Super + B opens the theme carousel (Up/Down picks a background), or run ohmydebn-theme-bg-next
• Build custom themes: Ctrl + Shift + A (Aether theme builder)
• Browse more themes: press B in the theme carousel (Ctrl + Super + T)

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.

Preferred: the user's own keybindings file. ~/.config/ohmydebn/keybindings.txt is applied on top of the stock keybindings by every ohmydebn-update, when the editor opened by ohmydebn-keybindings-edit closes, and by ohmydebn-keybindings-apply. It survives updates and can be copied to another OhMyDebn machine. Stock keybindings are addressed by NAME (the first quoted field in /usr/share/ohmydebn/install/keybinding/keybinding-custom.txt), never by slot number. Three verbs:

# add a keybinding, or change the stock keybinding of that name (command and/or key)
keybinding "Slack" "/usr/share/ohmydebn/bin/ohmydebn-launch-webapp https://slack.com" "['<Super>S']"
keybinding "Neovim" "/usr/share/ohmydebn/bin/ohmydebn-neovim" "['<Super>V']"
# remove a stock keybinding's key
keybinding-unbind "X"
# change a Cinnamon built-in (same verb and arguments as keybinding-cinnamon.txt)
keybinding-cinnamon "wm" "close" "['<Alt>F4']"

Workflow: ohmydebn-keybindings-edit (OhMyDebn Menu → Setup → Keybindings; creates the file from the commented template, opens it, applies on close) or edit the file and run ohmydebn-keybindings-apply. A key used by a keybinding line is freed from whichever stock keybinding had it. Deleting a line reverts that keybinding to stock on the next apply. Changes take effect immediately, no Cinnamon restart. ohmydebn-doctor reports a file that was edited but not applied. The Super + K page lists the stock keybindings only.

Do NOT write custom keybindings with raw gsettings - ohmydebn-update rewrites the stock slots and a stray slot number will collide with a future stock keybinding. Use the file above. Cinnamon Settings (cinnamon-settings keyboard) is fine for one-off, machine-local tweaks of Cinnamon's own shortcuts.

View current bindings:

• gsettings list-recursively org.cinnamon.desktop.keybindings.wm
• /usr/share/ohmydebn/install/keybinding/*.txt for the stock OhMyDebn bindings

When re-binding a key that is already used: check the stock files first and tell the user what the key was bound to before, e.g. "Note: Super+X was bound to X.com; it now opens Slack." ohmydebn-keybindings-apply prints the same information when it frees a key.

Display/Monitors

Configure through Cinnamon Settings > Displays or via command line:

# List displays
xrandr

# Configure display (example)
xrandr --output eDP-1 --mode 1920x1080 --pos 0x0 --output HDMI-A-1 --mode 2560x1440 --pos 1920x0

Window Management

Cinnamon window management is configured through:

• Cinnamon Settings > Windows: Window behavior, tiling, workspaces
• Cinnamon Settings > Workspaces: Workspace configuration
• Manual editing: gsettings set org.cinnamon.desktop.wm.preferences <key> <value> or dconf-editor

For advanced window management, additional extensions can be installed from Cinnamon Spices.

Window Tiling

Basic Window Tiling:

• Super + Left/Right/Up/Down: Tile window to respective screen half
• Combine arrows for corner tiling (e.g., Super + Up then Right for upper right)
• No window gaps, maximizes screen area

Advanced Window Tiling (gTile Extension):

• Ctrl + Shift + G: Display gTile overlay
• Grid options: 2x2, 3x2, 4x4, or 6x6 (press 1, 2, 3, or 4 to select)
• Select tiles by pressing letter keys (e.g., 'a' then 'n' for left half in 4x4)
• Press same letter twice for single tile (e.g., 'a' twice for upper left corner)

gTile Hotkeys with Window Gaps:

• Ctrl + Shift + 1/2/3 (numpad): Bottom corners/half with gaps
• Ctrl + Shift + 4 (numpad) or H: Left half with gaps
• Ctrl + Shift + 5 (numpad) or Enter: Full screen with gaps
• Ctrl + Shift + 6 (numpad) or L: Right half with gaps
• Ctrl + Shift + 7/8/9 (numpad): Top corners/half with gaps

Configure gTile:

• System Settings → Extensions → gTile → Configure → Behavior tab

Fonts

Fonts are managed through Cinnamon Settings > Fonts, which provides options to:

• Change interface font, document font, monospace font, and window title font
• Adjust font rendering settings (hinting, antialiasing, scaling factor)
• Set font sizes for different UI elements

Caskaydia Nerd Font is included by default for terminal icons and glyphs.

OhMyDebn Utilities

Additional tools available in OhMyDebn:

• OhMyDebn Logo: Ctrl + Shift + O (display animated logo)
• OhMyDebn Demo: Ctrl + Alt + D (animated logo showcase)
• System Summary: GUI version of fastfetch via OhMyDebn menu or Ctrl + Shift + S
• System Monitoring: btop performance monitor via Super + T
• Audio Visualization: Cava via terminal or Ctrl + Super + A

System

ohmydebn-update                  # Full system update (also updates installed AI tools such as OpenCode)
ohmydebn-version                 # Show OhMyDebn version

System control (lock, shutdown, reboot) is handled through:

• Cinnamon Menu (power options) or OhMyDebn Menu
• Hotkeys: Ctrl + Alt + L (lock), Ctrl + Alt + End (shutdown), Ctrl + Alt + Del (logout)
• Standard system commands: loginctl lock-session, shutdown now, reboot

Troubleshooting

# Reset all configured apps to defaults
ohmydebn-reset-config

# Full reinstall of OhMyDebn deb package
sudo /usr/bin/apt install --reinstall ohmydebn

Decision Framework

When user requests system changes:

1. Is it a stock ohmydebn command? Use it directly
2. Is it a config edit? Edit in ~/.config/, never ~/.local/share/ohmydebn/
3. Is it a theme customization? Create a NEW custom theme directory
4. Is it a package install? Use apt or ohmydebn-pkg-install
5. Unsure if command exists? Search with ls /usr/share/ohmydebn/bin/ | grep ohmydebn

Development (AI Agents)

When contributing to OhMyDebn itself (e.g., fixing bugs, adding features), the install process is designed to be idempotent and can be run multiple times.

Update Process

When a user runs ohmydebn-update, it first installs the latest ohmydebn package and then goes through the install process again so they get the new changes. The install process is idempotent, meaning:

• It can be safely run multiple times without causing issues
• It will only apply new changes needed
• Existing configurations are preserved unless explicitly updated
• Dependencies are checked and installed as needed

Development workflow:

1. Make changes to the OhMyDebn source code in /usr/share/ohmydebn/
2. Test the changes by running the install scripts
3. Users get updates by running ohmydebn-update
4. The install process automatically handles applying new settings, dependencies, and configurations

Installation scripts in /usr/share/ohmydebn/install/ handle:

• Installing system dependencies via apt
• Setting up default configurations
• Creating necessary directories and symlinks
• Updating user configurations with new defaults

Example Requests

• "Change my theme to catppuccin" -> ohmydebn-theme-set catppuccin or OhMyDebn Menu → Style → Theme
• "Add a keybinding for Super+E to open file manager" -> Super+E is already GMail, so pick a free key or retarget it: add a line to ~/.config/ohmydebn/keybindings.txt (see Customizing keybindings above) and run ohmydebn-keybindings-apply
• "Configure my external monitor" -> Use Cinnamon Settings > Displays or xrandr command
• "Make the window animations faster" -> Edit Cinnamon Settings > Effects or gsettings set org.cinnamon window-effect-speed <value>
• "Set up custom terminal prompt" -> Edit ~/.config/starship.toml or use Starship presets
• "Build a theme from this wallpaper" -> Ctrl + Shift + A (Aether theme builder)
• "Reset all configurations to defaults" -> ohmydebn-reset-config
• "Take a screenshot of an area" -> Shift + Print or Ctrl + Shift + Print (to clipboard)
• "Show system information" -> Ctrl + Shift + S (fastfetch)
• "Open OhMyDebn menu" -> Super + Space
• "Launch AI assistant" -> Super + A (the default assistant, set in Setup > Defaults > Agent) or from Apps > AI
• "Update OpenCode to latest version" -> ohmydebn-update (updates OpenCode if it's installed)
• "Open apps menu" -> Super + R (GTK app launcher)
• "Show OhMyDebn logo" -> Ctrl + Shift + O
• "Show system summary" -> Ctrl + Shift + S (fastfetch GUI)
• "Monitor system performance" -> Super + T (btop)
• "Visualize audio" -> cava in terminal or Ctrl + Super + A