Omarchy User Finalization: The 9-Step Provisioning Process Explained

Omarchy user finalization is a nine-step configuration sequence performed by the omarchy-provision-user command that converts a fresh home directory—populated from the static /etc/skel template—into a fully functional desktop environment with AI skills, application defaults, and hardware-specific tuning.

The basecamp/omarchy repository separates new user provisioning into three distinct phases: seed, finalize, and resync. While the seed phase merely copies static files from /etc/skel to $HOME, the finalize phase executes dynamic, per-user configuration that cannot be handled by the read-only skeleton tree. This article breaks down the technical implementation of Omarchy user finalization as documented in docs/file-layout.md and implemented across the core command binaries.

The Three-Phase Provisioning Model

Omarchy treats user creation as a pipeline with clearly separated responsibilities:

1. Seed – Copies static defaults from /etc/skel into the user's home directory.
2. Finalize – Executes omarchy-provision-user (also exposed as omarchy finalize user) to perform dynamic configuration requiring runtime environment awareness.
3. Resync – Handles ongoing synchronization of dotfiles and environment updates.

The finalization phase runs once per user immediately after the seed completes, triggered either during ISO installation via omarchy-provision-user --force --first-install or deferred to first boot via omarchy-provision-owner.

The Nine Steps of Omarchy User Finalization

According to the runtime sequence defined in docs/file-layout.md (lines 95–119), the omarchy-provision-user command performs the following operations in order:

1. AI Skill Symlink Creation

The finalizer iterates over every skill directory under default/agents/skills/—such as omarchy and diagnose-crash—and creates symbolic links in the user's agent directories. These links point to:

• ~/.agents/skills/<name>
• ~/.claude/skills/<name>
• ~/.codex/skills/<name>
• ~/.pi/agent/skills/<name>

This architecture allows users to execute the latest skill scripts directly from the repository without copying files into their home directories, ensuring updates propagate immediately.

2. XDG User Directory Initialization

The command executes xdg-user-dirs-update to refresh the XDG user-directories specification. This ensures that standard folders like Desktop, Documents, and Downloads are correctly populated under $HOME after the initial skeleton copy.

3. GTK Bookmarks Configuration

The finalizer regenerates ~/.config/gtk-3.0/bookmarks to reflect the current $HOME layout. This updates the "Places" sidebar in GTK-based file managers such as Nautilus or Thunar to display the user's actual directory structure rather than stale template paths.

4. Hyprland Keyboard Layout Defaults

Instead of rewriting per-user Hyprland configuration files, the finalizer ensures the Wayland compositor reads its keymap settings (XKBLAYOUT and XKBVARIANT) from the central /etc/vconsole.conf file. This maintains consistency between the system console and the graphical environment without duplicating keyboard layout definitions in $HOME.

5. Default Application Assignment

The script calls xdg-settings set default-web-browser and xdg-mime default to establish the system's default web browser and mail handler within the user's MIME association database. This ensures that xdg-open and similar tools launch the correct applications for HTTP and mailto links.

6. Application Launcher Refresh

Running omarchy-refresh-applications regenerates .desktop entry files for installed applications. This guarantees that the application menu reflects the current system state, including any newly installed packages or removed software, without requiring a full session restart.

7. Per-User Install Script Execution

The finalizer sources install/user/all.sh, which encapsulates the bulk of user-specific configuration:

• Installing and activating themes
• Configuring Chromium browser defaults
• Setting up Git configuration and credentials
• Installing mise (the universal version manager)
• Provisioning the GPG keyring
• Applying hardware-specific quirks such as ASUS microphone fixes

This script runs in the context of the target user, ensuring all changes are owned by the correct UID.

8. First-Install Migration Marking

When invoked with the --first-install flag, the finalizer records every shipped user migration as already applied. This prevents migration scripts from executing again for newly created users, avoiding redundant operations and potential configuration drift on fresh installations.

9. Idempotency Marker Creation

Upon successful completion, omarchy-done writes a completion marker to ~/.local/state/omarchy/done/finalize-user. Subsequent executions of omarchy-provision-user detect this file and exit immediately as no-ops, making the process safe to run repeatedly without side effects.

Manual Execution and Debugging

While the ISO installer automatically triggers finalization via omarchy-provision-user --force --first-install, administrators can manually invoke the process for troubleshooting or user repair:

# Standard finalization (exits immediately if marker exists)

omarchy provision-user

# Force re-execution, ignoring the idempotency marker

omarchy provision-user --force

# First-install mode: marks all migrations as applied before running

omarchy provision-user --first-install

The --force flag is particularly useful when testing changes to install/user/all.sh or when recovering from a failed initial setup.

Key Implementation Files

Understanding the Omarchy user finalization architecture requires familiarity with these critical paths in the basecamp/omarchy repository:

• bin/omarchy-provision-user – The primary entry point that implements the nine-step sequence and handles CLI flags like --force and --first-install.
• docs/file-layout.md – Documents the runtime finalization sequence and the distinction between seed, finalize, and resync phases (lines 95–119).
• install/user/all.sh – The comprehensive per-user installation script responsible for themes, browsers, Git, mise, GPG, and hardware quirks.
• default/agents/skills/omarchy/SKILL.md – Defines the skill directory structure that gets symlinked into user agent directories during step one.
• ~/.local/state/omarchy/done/finalize-user – The runtime idempotency marker that prevents duplicate executions.

Summary

• Omarchy user finalization consists of nine sequential steps executed by omarchy-provision-user after the static /etc/skel seed.
• The process creates symlinks for AI skills, initializes XDG directories, updates GTK bookmarks, and configures Hyprland keyboard layouts from system defaults.
• Application defaults and launcher menus are refreshed through xdg-settings and omarchy-refresh-applications.
• The heavy lifting occurs in install/user/all.sh, which handles themes, browsers, Git, mise, GPG, and hardware fixes.
• Idempotency is guaranteed by a marker file in ~/.local/state/omarchy/done/, with --force available to override when necessary.

Frequently Asked Questions

What distinguishes the seed phase from the finalize phase in Omarchy?

The seed phase copies static, read-only files from /etc/skel into $HOME, while the finalize phase executes dynamic configuration through omarchy-provision-user that requires runtime environment awareness, such as creating symlinks to repository skills or setting up per-user GPG keys.

How can I re-run the user finalization process if something went wrong during installation?

Execute omarchy provision-user --force to bypass the idempotency check at ~/.local/state/omarchy/done/finalize-user and re-execute all nine configuration steps. Use --first-install if you also need to mark migrations as applied for a fresh user environment.

Where does Omarchy store the completion marker to prevent duplicate finalization runs?

After successful execution, the system writes an empty file to ~/.local/state/omarchy/done/finalize-user. The omarchy-provision-user command checks for this file before running and exits immediately if found, unless the --force flag is provided.

What happens during the skill symlink creation step?

The finalizer scans default/agents/skills/ and creates symbolic links in the user's home directory under ~/.agents/skills/, ~/.claude/skills/, and similar agent-specific paths. This allows AI assistants to access the latest skill scripts directly from the repository without requiring file copies that would become stale.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}