omarchy

Omarchy スキル

Omarchy Linux システムを管理します - Hyprland を採用した、美しく楽しいエージェント志向の Arch Linux ディストリビューションです。

このスキルは、インストール済みシステムのエンドユーザー向けカスタマイズを対象としています。 Omarchy のソースコードへのコントリビュートを目的としたものではありません。

トピックガイド

よく使う領域についてのより詳細な手順は、このファイルの隣にあります。開始する前に 該当するガイドを読んでください:

• hyprland.md - キーバインド、モニター、ウィンドウルール、その他の Hyprland 設定
• plugins.md - Omarchy シェル: バーのレイアウト、ウィジェット、プラグイン、アイドル動作
• theming.md - テーマ、背景、フォント
• hooks.md - システムイベントで実行される自動化フック
• capture.md - スクリーンショット、画面録画、OCR テキストキャプチャ、ファイル共有
• contributing.md - Omarchy のバグ報告と修正のアップストリームへの提出

重要な安全ルール

特権コマンドについては、以下の権限昇格のルールに従ってください: パスワードプロンプト用のターミナルが利用できる場合は sudo、利用できない場合は pkexec を使用します。それ自体で権限昇格を管理するコマンドをラップしないでください。

エンドユーザー向けのカスタマイズ作業では、/usr/share/omarchy/ にあるものを決して変更しないでください - ただし、読み取りは安全であり、推奨されます。

このディレクトリは omarchy パッケージが所有しています。ローカルでの変更は、 次回の omarchy update で上書きされます。

/usr/share/omarchy/     # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/                    # Command source (packaged binaries are on PATH)
├── config/                 # Default config templates
├── themes/                 # Stock themes
├── default/                # System defaults
├── shell/                  # Omarchy shell source and defaults
├── migrations/             # Update migrations
└── install/                # Installation scripts

/usr/share/omarchy/ の読み取りは安全で役立ちます - 以下のために自由に行ってください:

• omarchy コマンドの動作を理解する: omarchy theme set --help または cat $(which omarchy-theme-set)
• カスタマイズ前にデフォルト設定を確認する: cat "$OMARCHY_PATH/config/omarchy/shell.json"
• カスタマイズ用にコピーする標準テーマファイルを確認する
• デフォルトの hyprland 設定を参照する: cat /usr/share/omarchy/default/hypr/*

代わりに、常にこれらの安全な場所を使用してください:

• ~/.config/ - ユーザー設定 (編集しても安全)
• ~/.config/omarchy/themes/<custom-name>/ - カスタムテーマ
• ~/.config/omarchy/hooks/ - カスタム自動化フック

Omarchy 自体の開発を求めるリクエストの場合、このスキルは対象外です。このスキルではなく、リポジトリの開発手順に従ってください。

権限昇格

表示されているターミナルで実行する対話型スクリプトやコマンドでは、特権を必要とする 作業に sudo を使用します。Omarchy は特定のコマンドに対してパスワードなしの sudo アクセスを許可している場合があり、パスワードが必要なときはターミナルが適切な要求場所 です。

pkexec は、呼び出し元がターミナルと対話できない場合、またはそこでパスワードを 入力できない場合にのみ使用します。たとえば、エージェントによって起動されたコマンドや グラフィカルなバックグラウンドプロセスなどです。コマンドがシステム状態を変更するという だけの理由で sudo を pkexec に置き換えないでください。

システムアーキテクチャ

Omarchy は以下で構成されています:

コンポーネント	目的	設定場所
Arch Linux	ベース OS	/etc/、~/.config/
Hyprland	Wayland コンポジター/WM	~/.config/hypr/
Omarchy シェル	ステータスバー + 通知 (Quickshell)	~/.config/omarchy/shell.json
ランチャー/メニュー	Quickshell メニュー	~/.config/omarchy/extensions/omarchy-menu.jsonc
Alacritty/Foot/Kitty/Ghostty	ターミナル	~/.config/<terminal>/
Omarchy OSD	オンスクリーンディスプレイ	Quickshell プラグイン

コマンドの探索

Omarchy は単一の omarchy CLI を提供しており、omarchy <group> <action> を介してすべての omarchy-* バイナリにディスパッチします。常にこの形式を優先してください — 自己文書化されており、安定しています。基盤となる omarchy-* バイナリは依然として PATH 上に存在し、ソースを読むのは安全なままです。

# List every documented command and its summary (--all includes hidden commands)
omarchy commands

# Show the commands inside a group
omarchy theme --help
omarchy refresh --help
omarchy restart --help

# Show help for a specific command (does not execute it)
omarchy theme set --help

# Machine-readable listing (binary, route, summary, args, aliases)
omarchy commands --json

# Read a command's source to understand it
cat $(which omarchy-theme-set)

コマンドグループ

完全なリストを表示するには omarchy --help を実行してください。最も一般的なグループは次のとおりです:

グループ	目的	例
omarchy refresh	設定をデフォルトにリセットします（最初にバックアップされます）	omarchy refresh shell
omarchy restart	サービス/アプリを再起動します	omarchy restart shell
omarchy toggle	機能をオン/オフに切り替えます	omarchy toggle nightlight
omarchy theme	テーマ管理	omarchy theme set <name>
omarchy bar	バーのレイアウトとウィジェット	omarchy bar move omarchy.clock --section right
omarchy plugin	シェルプラグインの管理/クローン	omarchy plugin clone omarchy.clock
omarchy hook	自動化フックのインストール	omarchy hook install theme-set <script>
omarchy install	オプションのソフトウェア/パッケージのインストール	omarchy install docker dbs
omarchy launch	アプリの起動	omarchy launch browser
omarchy capture	スクリーンショットと録画	omarchy capture screenshot
omarchy reminder	デスクトップ通知リマインダー	omarchy reminder 15 "Pickup Jack"
omarchy pkg	パッケージ管理	omarchy pkg add <pkg>
omarchy setup	対話形式のセットアップウィザード	omarchy setup security fingerprint
omarchy update	システムアップデート	omarchy update

設定ファイルの場所

Hyprland の設定は ~/.config/hypr/ にあります — hyprland.md を参照してください。 Omarchy シェル（バー、通知、プラグイン、アイドル）は ~/.config/omarchy/shell.json で設定します — plugins.md を参照してください。

ターミナル

~/.config/alacritty/alacritty.toml
~/.config/foot/foot.ini
~/.config/kitty/kitty.conf
~/.config/ghostty/config

コマンド: omarchy restart terminal

その他の設定

アプリ	場所
btop	~/.config/btop/btop.conf
fastfetch	/etc/fastfetch/config.jsonc がデフォルト; ~/.config/fastfetch/config.jsonc がユーザーによる上書き
lazygit	~/.config/lazygit/config.yml
starship	~/.config/starship.toml
git	~/.config/git/config

安全なカスタマイズパターン

ユーザー設定を直接編集する

簡単な変更の場合は、~/.config/ 内のファイルを編集します:

# 1. Read current config
cat ~/.config/hypr/bindings.lua

# 2. Backup before changes
cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak.$(date +%s)

# 3. Make changes with Edit tool

# 4. Apply changes
# - Hyprland: auto-reloads on save, but MUST validate with `hyprctl reload` and `hyprctl configerrors`
# - Omarchy shell: shell.json and user plugin code under ~/.config/omarchy/plugins/ hot-reload on save
# - Menus/launcher: ~/.config/omarchy/extensions/omarchy-menu.jsonc hot-reloads on save
# - Terminals: apply with `omarchy restart terminal` (reloads running terminals; foot picks changes up in new windows)

デフォルトへのリセット -- 実行する前に必ずユーザーの確認を求めてください

カスタマイズがうまくいかなくなった場合:

# Reset specific config (creates backup automatically)
omarchy refresh shell
omarchy refresh hyprland

# The refresh command:
# 1. Backs up current config with timestamp
# 2. Copies default from $OMARCHY_PATH/config/
# 3. Restarts the component where the refresh needs it (e.g. `refresh shell`)

システムコマンド

omarchy update                  # Full system update
omarchy version                 # Show Omarchy version
omarchy debug --no-sudo --print # Debug info (ALWAYS use these flags)
omarchy system lock             # Lock screen
omarchy system shutdown         # Shutdown
omarchy system reboot           # Reboot

重要: ターミナルがハングする原因となる対話形式の sudo プロンプトを避けるため、常に omarchy debug を --no-sudo --print フラグ付きで実行してください。

トラブルシューティング

# Get debug information (ALWAYS use these flags to avoid interactive prompts)
omarchy debug --no-sudo --print

# Reset specific config to defaults
omarchy refresh <app>

# Refresh specific config file
# config-file path is relative to ~/.config/
# eg. `omarchy refresh config hypr/hyprland.lua` will refresh ~/.config/hypr/hyprland.lua
omarchy refresh config <config-file>

# Full reinstall of configs (nuclear option)
omarchy reinstall

判断フレームワーク

ユーザーがシステム変更を要求した場合:

1. それは標準の omarchy コマンドですか? それを直接使用します
2. それは設定の編集ですか? ~/.config/ で編集し、決して /usr/share/omarchy/ では編集しません
3. それはテーマのカスタマイズですか? theming.md に従い、新しいカスタムテーマディレクトリを作成します
4. それは自動化ですか? hooks.md に従い、omarchy hook install とフックの .d ディレクトリを使用します
5. それはパッケージのインストールですか? omarchy pkg add <pkgs...> を使用します（AUR 専用パッケージの場合は omarchy pkg aur add <pkgs...>）
6. それは組み込みのシェル/プラグインのコードですか? plugins.md に従い、omarchy plugin clone でクローンし、パッケージ化されたコピーは決して編集しません
7. コマンドが存在するか不明ですか? omarchy commands を実行します（または1つのグループについては omarchy <group> --help）

リマインダーのリクエスト

ユーザーがリマインダーの設定を求めた場合は、omarchy reminder <minutes> [message] を直接使用します。自然言語の期間を分に変換し、必要に応じて短いリマインダーラベルをタイトルケースにします。

omarchy reminder 15 "Pickup Jack"
omarchy reminder 60 "Check laundry"
omarchy reminder show
omarchy reminder clear

対象範囲外

このスキルは、Omarchy のソース開発を意図的に対象としていません。次の用途にはこのスキルを使用しないでください:

• /usr/share/omarchy/ 内のファイルの編集（bin/、config/、default/、shell/、themes/、migrations/ など）
• マイグレーションの作成または編集
• omarchy dev ... コマンドの実行

リクエスト例

• 「テーマを catppuccin に変更して」 -> omarchy theme set catppuccin
• 「Super+E でファイルマネージャーを開くキーバインドを追加して」 -> まず既存のバインドを確認し、o.rebind で既存のものを置き換えるか、o.bind で ~/.config/hypr/bindings.lua に追加します
• 「外付けモニターを設定して」 -> ~/.config/hypr/monitors.lua を編集します
• 「ウィンドウの隙間を小さくして」 -> ~/.config/hypr/looknfeel.lua を編集します
• 「ナイトライトをオンにして」 -> omarchy toggle nightlight（時間ベースのスケジュールには、~/.config/hypr/hyprsunset.conf のプロファイルを編集してから omarchy restart hyprsunset を実行します）
• 「15 分後に Jack を迎えに行くリマインダーを設定して」 -> omarchy reminder 15 "Pickup Jack"
• 「リマインダーを表示して」 -> omarchy reminder show
• 「すべてのリマインダーを消去して」 -> omarchy reminder clear
• 「catppuccin テーマの色をカスタマイズして」 -> オーバーレイ: 編集した colors.toml を ~/.config/omarchy/themes/catppuccin/ に置き、テーマを再適用します（theming.md を参照）
• 「テーマを変更するたびにスクリプトを実行して」 -> omarchy hook install theme-set <script> でインストールします
• 「ワークスペースラベルの描画方法を変更して」 -> omarchy.workspaces をクローンします。これによりバーが <username>.workspaces に切り替わるので、クローンを編集します
• 「10 分後にロックして」 -> ~/.config/omarchy/shell.json で idle.lock を 600 に設定します
• 「シェル/バーをデフォルトにリセットして」 -> omarchy refresh shell
• 「画面を録画して」 -> omarchy screenrecord --fullscreen、その後 omarchy screenrecord --stop-recording（capture.md を参照）
• 「このバグを Omarchy に報告して」 -> 診断情報と問題のキャプチャを集めてから報告します（contributing.md を参照）