Omarchy Roadmap: Planned Features and Architecture Improvements

The Omarchy roadmap focuses on hardening its unified update pipeline, with active development targeting automatic pacnew handling, refined pacman guard policies, and cleaner migration notification tools.

The Omarchy project—maintained at basecamp/omarchy—is an opinionated Arch Linux distribution centered on a single, coordinated update mechanism. According to the source code and design documents in docs/update-process.md, the roadmap prioritizes stability and user safety over rapid feature expansion, concentrating improvements on the core omarchy update workflow and its supporting subsystems.

Core Architecture Goals in the Omarchy Roadmap

The roadmap is anchored by four structural pillars that dictate how updates and system changes propagate. These components are already functional but continue to receive incremental refinements.

Unified Update Flow

The omarchy update command owns the entire upgrade process end-to-end. In bin/omarchy-update, the orchestrator coordinates package upgrades via pacman, per-user migrations, system snapshots, and UI refreshes in a strict sequence. This centralized control prevents partial upgrade states and ensures that post-installation hooks execute in the correct order.

Per-User Migration System

After pacman completes system-level changes, omarchy-migrate executes scripts from the migrations/*.sh directory. These migrations run with access to $HOME, DBus, and the graphical session, allowing them to adjust user-specific configurations that depend on newly installed system packages. Each release adds new migration scripts to this directory, and the system tracks which migrations have already run.

Guarded Pacman Usage

Direct invocation of pacman -Syu is blocked by an ALPM hook named 00-omarchy-update-guard.hook, which executes omarchy-update-pacman-guard. This mechanism ensures that users route through omarchy update instead of performing unsupervised system upgrades that might skip critical migration steps. The guard scope remains under evaluation, as the team acknowledges potential conflicts with legitimate package-manager front-ends.

Dev-Linked Checkout Channel

For developers and early adopters, the dev channel bypasses traditional package updates. Instead, omarchy-update-dev (called from the main update pipeline) fast-forwards a local git checkout to the latest commit. This allows rapid iteration without waiting for package builds, though future roadmap items may tighten the integration between dev checkouts and the stable migration system.

Explicit Roadmap Items and Future Directions

The repository’s documentation captures specific planned improvements that address current limitations and technical debt.

Automatic Pacnew and Pacsave Handling

The update process currently lacks automated handling for pacnew and pacsave files created during package upgrades. According to docs/update-process.md, this is flagged as "still missing" and represents a priority item for the next development cycle. The planned implementation will automatically detect these configuration fragments after an update and present user-friendly prompts for merging or cleanup, reducing the manual maintenance burden typical of Arch-based systems.

Refined Pacman Guard Scope

The current pacman guard may be overly restrictive, blocking some legitimate front-end tools unnecessarily. The roadmap includes tuning omarchy-update-pacman-guard to allow trusted package-manager wrappers while maintaining protection against unsupervised pacman -Syu invocations. This refinement aims to balance security with flexibility for power users who prefer alternative package management interfaces.

Migration Notification Consolidation

Internal tooling cleanup includes renaming omarchy-migrate-notify to a clearer public-facing name and deprecating compatibility wrappers like omarchy-update-user-notify. These changes consolidate the notification helpers into a single, well-documented interface that scripts and desktop environments can rely on for alerting users to pending migrations.

Additional Update Helpers and Maintenance Modules

Two potential commands are flagged for future inclusion: omarchy-update-time and omarchy-update-firmware. Currently marked as questions in the roadmap, these may migrate into dedicated maintenance modules that handle system clock synchronization and firmware updates outside the standard package flow. Additionally, the project continues to support omarchy-update-aur-pkgs for AUR management while evaluating whether to phase this out once the core package set stabilizes.

Checking for Pending Migrations

You can verify whether migrations are waiting to run using the built-in pending check. This pattern is useful for scripting custom notification workflows:

# Show any pending per-user migrations

omarchy-migrate --pending

# If migrations exist, the command exits 0 and prints their names.

# Combine with a notification in scripts:

if omarchy-migrate --pending; then
  omarchy-notification-send "Omarchy migrations pending – run \`omarchy-migrate\`"
fi

This functionality is implemented in bin/omarchy-migrate and documented in the migration-pending logic section of docs/update-process.md.

Key Files to Monitor

Track these paths to follow roadmap implementation progress:

• bin/omarchy-update – Central update orchestrator that coordinates the entire pipeline.
• bin/omarchy-migrate – Per-user migration runner that executes scripts from the migrations directory.
• docs/update-process.md – Comprehensive design document containing the "Remaining concerns" section where roadmap items are tracked.
• migrations/*.sh – Individual migration scripts; new features often debut here as upgrade steps.
• agents/skills/visual-verification.md – Guidelines for UI-level testing, supporting the roadmap's documentation and UX improvement goals.
• docs/menu.md – Menu schema definitions; UI changes from roadmap items typically update this file.

Summary

The Omarchy roadmap emphasizes reliable, user-centric update mechanics over feature bloat. Key upcoming developments include:

• Automatic detection and handling of pacnew/pacsave files to eliminate manual configuration merging.
• Fine-tuned pacman guard logic that distinguishes between dangerous direct upgrades and legitimate front-end usage.
• Notification tool consolidation to streamline the migration alerting system.
• Expanded documentation and visual test coverage for safer UI customizations and clearer migration safety procedures.

All roadmap items are traceable in basecamp/omarchy via the docs/update-process.md document and the evolving migrations/ script collection.

Frequently Asked Questions

When will automatic pacnew handling be implemented in Omarchy?

Automatic pacnew and pacsave handling is currently documented as "still missing" in docs/update-process.md and represents an active priority for the development team. While no specific release date is committed in the source repository, the feature appears in the immediate roadmap alongside other update pipeline refinements.

Why does Omarchy block direct pacman commands?

The ALPM hook 00-omarchy-update-guard.hook enforces usage of omarchy update to ensure that system upgrades never skip the per-user migration steps defined in bin/omarchy-migrate. This prevents configuration drift and partial upgrade states that could break the desktop environment. The team acknowledges this may inconvenience users of certain package front-ends and plans to refine the guard scope in future releases.

How do I check if migrations are pending after an Omarchy update?

Run omarchy-migrate --pending to check for unapplied migrations. This command exits with status 0 and prints migration names if any are waiting, making it suitable for shell scripts that trigger desktop notifications or automation hooks. The migrations themselves should then be executed by running omarchy-migrate without flags.

What is the difference between the stable and dev update channels in Omarchy?

The stable channel updates Omarchy through traditional pacman packages, while the dev channel uses omarchy-update-dev to fast-forward a local git checkout to the latest commit. The dev channel bypasses package building for rapid testing but may require manual intervention since it skips the structured migration pipeline used in stable releases.

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