How to Debug Omarchy Issues: A Complete Guide to System Diagnostics and Troubleshooting

Run omarchy debug to capture a comprehensive system snapshot, or use omarchy debug-idle for idle-state problems, then upload logs to logs.omarchy.org for sharing with maintainers.

Debugging Omarchy issues requires understanding the three built-in diagnostic binaries shipped with every installation. These tools—omarchy-debug, omarchy-debug-idle, and omarchy-upload-log—are intentionally included in the bin/ directory so users can generate reproducible environment snapshots without installing extra software. This guide walks through each tool, the CLI router introspection features, and shell-specific debugging methods based on the Omarchy source code.

Core Debugging Tools in bin/

Omarchy's diagnostics suite consists of three auto-generated helper scripts. According to the repository's docs/file-layout.md, these binaries are deliberately part of the official file layout.

omarchy-debug: The Primary Diagnostic Collector

The main debugging script lives at bin/omarchy-debug. It gathers:

• System information via inxi -Farz
• Kernel ring buffer output from dmesg (requires sudo)
• Journal warnings via journalctl -b -p 4..1
• List of installed packages

By default, it writes everything to /tmp/omarchy-debug.log and presents an interactive menu.

# Run the full interactive flow

omarchy debug

# Or call the binary directly

bin/omarchy-debug

The core implementation, visible in bin/omarchy-debug, handles privileged access like this:

# Decide whether to capture dmesg

if [[ $NO_SUDO = "true" ]]; then
  DMESG_OUTPUT="(skipped - --no-sudo flag used)"
else
  DMESG_OUTPUT="$(sudo dmesg)"
fi

# Write collected information to the log file

cat > "$LOG_FILE" <<EOF
...
$(inxi -Farz)
...
$(journalctl -b -p 4..1)
...
EOF

omarchy-debug-idle: Idle-State Diagnostics

For problems related to screensaver timeouts, lock behavior, or bar geometry, use bin/omarchy-debug-idle. This script mirrors omarchy-debug's structure but limits output to idle configuration and bar layout data from debugBarGeometry.

# Collect idle-related state only

omarchy debug-idle

omarchy-upload-log: Log Sharing

Both debug scripts call bin/omarchy-upload-log to push logs to https://logs.omarchy.org/ and receive shareable URLs. This uploader is designed as a standalone utility for any file-based sharing needs.

Debug Command Flags and Options

Control the debugging behavior with two key flags:

Flag	Effect
--no-sudo	Skips dmesg capture; use when you lack root access
--print	Outputs log to stdout instead of launching the interactive menu

# Non-interactive output for piping into tickets or chat

omarchy debug --no-sudo --print > /tmp/my-omarchy.log

# Print without sudo (useful for quick checks)

omarchy debug --no-sudo --print

CLI Router Introspection for Routing Issues

When commands resolve to unexpected binaries, use the CLI router's built-in help features documented in docs/cli-router.md.

# Show which binary a route resolves to

omarchy <route> --help

# Example: verify the theme command path

omarchy theme set --help

# Dump the complete routing table as JSON

omarchy commands --all --json

The router's resolution algorithm explains common "routing surprises": metadata moves, alias collisions, hidden commands, and typos. Inspect the full routing table with jq for targeted filtering:

omarchy commands --all --json | jq '.[] | select(.group=="theme")'

Shell-Specific Debugging for UI Issues

Visual problems—malformed bars, missing widgets, incorrect idle timeouts—require shell-level inspection. The Omarchy shell exposes debugBarGeometry, an IPC method that returns JSON bar layout data. This is documented in docs/omarchy-shell.md under the IPC methods table.

# Get bar geometry as formatted JSON

omarchy-shell debugBarGeometry | jq .

Complete Debugging Workflow

Follow this sequence when investigating Omarchy issues:

1. omarchy debug --no-sudo --print — Quick system diagnostics without elevation
2. omarchy debug — Full interactive flow; select Upload log for a shareable URL
3. omarchy debug-idle — Idle state and bar geometry when timeouts or layout fail
4. omarchy <route> --help — Verify binary resolution for routing problems
5. omarchy commands --all --json | jq . — Deep inspection of the routing table
6. omarchy-shell debugBarGeometry | jq . — UI layout debugging
7. omarchy version — Environment reproduction

Sharing Debug Information with Maintainers

When filing bugs on Discord or GitHub, include:

• The uploaded log URL from logs.omarchy.org
• Output of omarchy version

This combination gives maintainers a deterministic view of your environment.

# Complete example: upload and capture version

omarchy debug

# Select "Upload log" → copy the URL

omarchy version

Key Source Files for Debugging

File	Purpose
bin/omarchy-debug	Main diagnostics script; collects system info and writes /tmp/omarchy-debug.log
bin/omarchy-debug-idle	Idle-state and bar-geometry diagnostics
bin/omarchy-upload-log	Log uploader to logs.omarchy.org
docs/cli-router.md	CLI routing algorithm and introspection methods
docs/omarchy-shell.md	IPC methods including debugBarGeometry
manual/45-troubleshooting.md	User-facing troubleshooting documentation
docs/file-layout.md	Rationale for including debug binaries in releases

Summary

• Run omarchy debug to generate comprehensive system snapshots at /tmp/omarchy-debug.log
• Use --no-sudo --print for quick, non-interactive diagnostics suitable for copy-pasting
• Call omarchy debug-idle when investigating screensaver, lock, or bar layout issues
• Inspect routing with <route> --help and commands --all --json to resolve command resolution problems
• Query omarchy-shell debugBarGeometry for JSON bar layout data on UI glitches
• Upload logs to logs.omarchy.org and include omarchy version when reporting issues

Frequently Asked Questions

What permissions does omarchy debug require?

The debug script runs dmesg with sudo by default to capture kernel ring buffer data. Use --no-sudo to skip this step if you lack root access, though this omits potentially critical hardware and driver information from the log.

Where are debug logs stored before uploading?

Logs are written to /tmp/omarchy-debug.log with restricted permissions. The interactive menu offers three options: upload to logs.omarchy.org, view in a pager, or save a copy in the current working directory.

How do I debug a command that seems to run the wrong binary?

Use omarchy <route> --help to see the resolved binary path. For deeper investigation, run omarchy commands --all --json and filter with jq to examine metadata, aliases, and hidden command flags that might cause routing surprises.

What should I do if my bar looks wrong or widgets disappear?

Call omarchy-shell debugBarGeometry to get a JSON dump of the current bar layout. Pipe through jq . for readable formatting, then include this output in your bug report alongside a standard omarchy debug log.

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