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

> Debug Omarchy issues with `omarchy debug` or `omarchy debug-idle` to capture system snapshots. Upload logs to logs.omarchy.org for maintainer support and fast resolution.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/basecamp/omarchy/blob/main/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.

```bash

# 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:

```bash

# 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`.

```bash

# 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 |

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md).

```bash

# 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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) under the IPC methods table.

```bash

# 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.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) | CLI routing algorithm and introspection methods |
| [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) | IPC methods including `debugBarGeometry` |
| [`manual/45-troubleshooting.md`](https://github.com/basecamp/omarchy/blob/main/manual/45-troubleshooting.md) | User-facing troubleshooting documentation |
| [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/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.