How Omarchy Explicitly Resyncs Clamshell Display State: System-Wake Deep Dive

Omarchy performs explicit resync of clamshell display state through the omarchy system wake command, which restores brightness and invokes omarchy-hyprland-monitor-clamshell to reconcile monitor configuration with current hardware state.

When a laptop wakes from sleep with its lid closed and an external monitor connected, the window manager may retain stale display state. Omarchy solves this through a deliberate, test-verified resynchronization chain that queries hardware state and reconfigures Hyprland monitors accordingly. This mechanism ensures the internal laptop display correctly disables when clamshelled and re-enables when the lid opens.

The System-Wake Resync Entry Point

The explicit resync originates in bin/omarchy-system-wake. This script handles post-wake initialization, including display brightness restoration and—critically—the clamshell state check.

Resync Invocation Pattern

The wake script calls the clamshell helper with defensive error handling:

omarchy-hyprland-monitor-clamshell >/dev/null 2>&1 || true

This pattern accomplishes two goals:

• Output suppression — Monitor detection chatter doesn't pollute the wake log
• Fail-safety — Even if the clamshell script encounters errors, the wake sequence continues

The || true guard is intentional: display resync failure shouldn't prevent system wake completion.

The Clamshell Resync Implementation

The resync logic lives in bin/omarchy-hyprland-monitor-clamshell. This script bridges hardware state detection with Hyprland monitor management.

Hardware State Detection

The script determines clamshell status through dedicated hardware helpers:

• omarchy-hw-laptop-closed — Returns true if laptop lid is physically closed
• omarchy-hw-clamshell — Returns true if clamshell mode should activate (lid closed + external monitor present)

Monitor Reconciliation Flow

The script executes this decision tree:

1. Query current monitors via hyprctl monitors all -j
2. Identify internal display (typically eDP-1 or similar laptop panel)
3. Check manual-disable flag — Respects MANUAL_DISABLE_FLAG to avoid overriding user-initiated internal display disable
4. Apply state transition:
   • Lid closed + external connected → Disable internal, enable external
   • Lid opened → Re-enable internal display, clear disable flags
   • No external monitor → Maintain single-display configuration

The script handles edge cases like mirror mode detection and preserves user preferences across sleep/wake cycles.

Test Verification of Explicit Resync

Omarchy's test suite guarantees this behavior through test/shell.d/monitor-recovery-test.sh. The test validates that system wake includes mandatory clamshell resync:

grep -F 'omarchy-hyprland-monitor-clamshell >/dev/null 2>&1 || true' "$system_wake" >/dev/null
pass "system wake resyncs clamshell display state"

This assertion ensures:

• The exact resync command appears in the wake script
• Output redirection matches the expected pattern
• Error suppression via || true remains in place

The test fails if anyone removes or modifies the resync call, protecting against regression.

Practical Usage Examples

Trigger Full Wake and Resync Sequence

# Complete wake: brightness restore + clamshell resync

omarchy system wake

Manual Explicit Resync Without Wake

# Force resync independently—useful after hot-plugging monitors

omarchy-hyprland-monitor-clamshell

Scripting with Error Tolerance

# Same resilience pattern used internally

if omarchy-hyprland-monitor-clamshell >/dev/null 2>&1; then
    echo "Display state synchronized"
else
    echo "Resync completed with warnings"
fi

Key Source Files

File	Purpose	Location
bin/omarchy-system-wake	Entry point: brightness restore, resync trigger	bin/omarchy-system-wake
bin/omarchy-hyprland-monitor-clamshell	Core resync logic, hardware polling, monitor reconfiguration	bin/omarchy-hyprland-monitor-clamshell
test/shell.d/monitor-recovery-test.sh	Automated verification of resync behavior	test/shell.d/monitor-recovery-test.sh

Summary

• Explicit resync occurs via omarchy system wake, which unconditionally calls omarchy-hyprland-monitor-clamshell
• The clamshell script queries hardware state through omarchy-hw-* helpers and reconciles Hyprland monitor configuration
• Manual-disable flags prevent unwanted re-enabling of the internal display
• Defensive error handling (|| true) ensures wake completion regardless of resync success
• Test coverage in monitor-recovery-test.sh locks in this behavior against future changes

Frequently Asked Questions

Can I run the clamshell resync without waking the system?

Yes. Invoke omarchy-hyprland-monitor-clamshell directly. This is useful after connecting or disconnecting external monitors while the system remains awake. The script performs the same hardware detection and monitor reconfiguration as during system wake.

What happens if the clamshell script fails during wake?

The wake sequence continues normally. The resync call uses >/dev/null 2>&1 || true to suppress output and ignore exit codes. This design prevents display configuration issues from blocking system usability—users can still wake their laptop and manually run the resync later if needed.

How does Omarchy distinguish between clamshell mode and simply closing the laptop lid?

The omarchy-hw-clamshell helper checks two conditions: lid closure and presence of an external monitor. Lid closure alone doesn't trigger internal display disable—only when both conditions match does the script enter true clamshell configuration. This prevents accidental display shutdown when closing the laptop without external video.

Where is the manual-disable flag stored?

The MANUAL_DISABLE_FLAG is typically a state file in the Omarchy runtime directory. The clamshell script consults this flag before re-enabling the internal display, ensuring that explicit user choices (like hyprctl output eDP-1 disable) survive sleep/wake cycles. The flag clears automatically when the lid opens or through explicit enable commands.

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