macOS の全ディスプレイと全 Space の壁紙を一括ローテーションする kabe を作った

kabe は、macOS の全ディスプレイと全 Space（Mission Control）に対して、~/.kabe ディレクトリ内の画像を一括で壁紙ローテーションする zsh スクリプトです。ライトモードとダークモードを切り替えるタイミングで壁紙も一括で変えたい場合や、新幹線などの公共の場で目立つ背景を避けたい場合など、決まった順序で壁紙を一括適用したい場面で役立ちます。この記事では、kabe のインストールから実際の動作、そして内部で使う 2 つのバックエンドの役割までを紹介します。

どんな場面で役立つのか

kabe が特に役立つのは、次のような場面です。

• ライトモードとダークモードを切り替えるタイミングで、壁紙も明るさに合わせた画像に一括で変えたい
• 新幹線やカフェなどの公共の場で作業する時に、目立つ背景が気になるので無難な画像に切り替えたい
• Mission Control で Space を複数使っている場合、1 つずつ壁紙を設定するのではなく一括で適用したい

このような場面では、kabe を実行するだけで全ディスプレイ・全 Space の壁紙が決まった順序で切り替わります。

kabe をインストールする

必要なバックエンドをインストールする

Note

macos-wp が macOS 26 Tahoe を要求するため、kabe も macOS 26 Tahoe 以降で動作します。それより前のバージョンでは正常に動作しない可能性があります。

kabe は壁紙の適用処理をバックエンドに委譲しています。実行前に macos-wp と desktoppr を Homebrew でインストールします。

brew install marek-vybiral/macos-wp/macos-wp
brew install --cask desktoppr

macos-wp は macOS の壁紙設定を plist レベルで書き換えるツール、desktoppr は外部ディスプレイへの即時適用に特化したツールです。どちらも通常ユーザー権限でインストールします。

kabe 本体をインストールする

リポジトリの installer.sh をパイプで実行すると、バックエンドの存在を確認したうえで /usr/local/bin/kabe に配置されます。

curl -fsSL https://raw.githubusercontent.com/takumi3488/kabe/main/installer.sh | sh

ユーザー権限で書き込める場所に入れたい場合は、--prefix を渡します。

curl -fsSL https://raw.githubusercontent.com/takumi3488/kabe/main/installer.sh \
  | sh -s -- --prefix "$HOME/.local/bin"

インストーラーはリモートから kabe スクリプトをダウンロードし、実行権限を付与してコピーするだけの単純な作りです。ローカルで clone 済みの場合は、同じディレクトリから ./installer.sh --prefix "$HOME/.local/bin" を実行することもできます。

壁紙を一括ローテーションしてみる

壁紙ディレクトリを準備する

kabe は ~/.kabe ディレクトリ内の画像を辞書順に読み取ります。対応フォーマットは jpg、jpeg、png、gif、webp、heic です。以下のようにディレクトリを作成し、切り替えたい画像をコピーします。

mkdir -p ~/.kabe
cp ~/Pictures/wallpapers/* ~/.kabe/

初回実行

kabe を実行すると、最初の画像が壁紙として適用されます。

$ kabe
Wallpaper changed on all Spaces: none -> 001.jpg

none と表示されているのは、前回の状態がまだ記録されていないためです。実行後、~/.kabe/.last-wallpaper に選択した画像のパスが永続化されます。

2 回目以降のローテーション

再度 kabe を実行すると、辞書順で次の画像に進みます。

$ kabe
Wallpaper changed on all Spaces: 001.jpg -> 002.png

最後の画像まで進むと、先頭の画像に戻ってループします。毎回同じ順序で確実に回るため、何度実行しても予測可能です。

状態をリセットする

ローテーションを最初からやり直したい場合は、状態ファイル ~/.kabe/.last-wallpaper を削除します。次回の実行では、再び辞書順の最初の画像から始まります。

rm -f ~/.kabe/.last-wallpaper

なぜ 2 つのバックエンドを使うのか

kabe は macos-wp と desktoppr を両方呼び出すことが特徴です。それぞれの役割を整理します。

macos-wp が壁紙設定を永続化する

macos-wp は ~/Library/Application Support/com.apple.wallpaper/Store/Index.plist を原子性を保ちながら更新し、次の 2 箇所に壁紙を書き込みます。

• Displays.<DisplayUUID>: 将来作成される Space 用のデフォルト
• Spaces.<SpaceUUID>.Displays.<DisplayUUID>: 既存の Space 用の設定

更新前の plist は .bak として保持され、変更後に WallpaperAgent が再起動されます。これにより、再起動後や新しい Space を作成した後でも壁紙が維持されます。

desktoppr がアクティブな外部ディスプレイを即座に更新する

macos-wp だけでは、現在アクティブな外部ディスプレイに古い画像がキャッシュされたまま表示され続けることがあります。desktoppr は接続中の物理ディスプレイに対して即座に壁紙を上書きし、このキャッシュ問題を回避します。

"$macos_wp_bin" set "$next_image"
"$desktoppr_bin" "$next_image"

この 2 ステップにより、設定の永続化と表示の即時反映の両方を実現しています。

失敗時は状態を進めない

kabe はどちらかのバックエンドが失敗しても、.last-wallpaper を更新しません。これにより、壁紙の適用に失敗したのに次回から先に進んでしまうという事態を防ぎます。

"$macos_wp_bin" set "$next_image"
"$desktoppr_bin" "$next_image"

temporary_state="${state_file}.${RANDOM}"
print -r -- "$next_image" > "$temporary_state"
mv -- "$temporary_state" "$state_file"

状態ファイルは一時ファイルに書き込んでから mv で置き換えるため、書き込み途中の破損も避けられます。

macOS 標準の設定ではディスプレイや Space ごとに異なる壁紙を永続的に保つことが難しく、動的な壁紙ローテーションにも対応していません。kabe はそのあたりをシェルスクリプトで機械的に解決し、任意の画像セットを決まった順序で全 Space・全ディスプレイに適用する用途に向いています。

まとめ

• kabe は ~/.kabe 内の画像を辞書順に一括ローテーションする zsh スクリプトです
• macos-wp と desktoppr を組み合わせることで、設定の永続化とアクティブディスプレイの即時反映を両立しています
• 実行のたびに次の画像へ進み、最後まで到達すると先頭に戻る予測可能なローテーションです
• バックエンドの失敗時には状態を進めず、一時ファイル経由で安全に状態を保存します
• ユースケースとしては、複数枚の壁紙を決まった順序で全 Space・全ディスプレイに反映させたい人向けです

参考

• takumi3488/kabe
• marek-vybiral/macos-wp
• scriptingosx/desktoppr