xbarが動かないときに見る場所｜権限、常駐、起動項目の順で確かめる

メニューバーに出したいプラグインを置いたのに、何も出ない。ターミナルでは正しく動くのに、メニューバーでは空欄になる。xbarの不具合として相談される内容は、この2つのどちらかにほぼ集約される。原因の大半は本体の故障ではなく、走らせ方の約束事のどこかが外れていることにある。

この記事は、症状ごとに見る場所を順番に並べたものである。上から順に確かめれば、たいていは3つ目までで原因に行き当たる。ここに書いた仕様は、2026年9月10日に配布元の公開ドキュメントで確認したものである。

症状を3つに切り分ける

最初にやることは、切り分けである。どこまで動いているかで、見る場所が変わる。

1つ目は、メニューバーにプラグインの項目そのものが現れない状態である。この場合、そもそもファイルがプラグインとして認識されていない可能性が高い。ファイル名の書式か、置き場所を疑う。

2つ目は、項目は現れるが中身が空、あるいはエラーらしき表示になる状態である。この場合、ファイルは認識されており、実行しようとして失敗しているか、実行はできたが出力が空である。実行権限、シェバン、PATHの順で疑う。

3つ目は、表示はされるが値が古いまま更新されない状態である。この場合、更新の間隔の指定か、変数の値の読み込みを疑う。

この3つを混ぜて調べ始めると遠回りになる。まず自分がどれなのかを決めてから、下の該当する節へ進むとよい。

ファイル名の書式と置き場所

項目が現れないときは、ここが原因であることが多い。プラグインのファイル名には決められた形があり、公開されているドキュメントには次のように書かれている。

The refresh time is in the filename of the plugin, following this format: {name}.{time}.{ext} 出典: github.com

名前と更新間隔と拡張子を、点でつないだ形である。更新間隔に使える書き方は、秒が10sのような形、分が1m、時間が2h、日が1dという形で示されている。date.1m.sh なら1分ごとに走る、という例が挙げられている。

この形から外れたファイル名、たとえば点が1つしかないものや、更新間隔の部分が数字と単位の組になっていないものは、読み込まれないか意図しない間隔で走ることになる。拡張子は言語に合わせて付ける。

置き場所も確かめておきたい。プラグインを置くフォルダは、利用者のライブラリの中にあるアプリケーションサポートの下、アプリ名のフォルダの中のpluginsである。以前の名前の道具から移ってきた場合は、古いフォルダに置いたままになっていないかを見る。公開ページにも、以前の道具から移る場合はプラグインをこの新しいフォルダへ移すように、という案内がある。

実行権限とシェバン

項目は出るが中身が空、という場合の最初の容疑者がこれである。ドキュメントは実行権限について明確に書いており、chmod +x で実行可能にすることを求めている。ダウンロードしてきたファイルや、テキストエディタで新規に作ったファイルは、実行権限が付いていないことがある。

シェバンについても指定がある。ドキュメントでは #!/usr/bin/env の形を使うことが推奨されており、bashで書くなら1行目を #!/usr/bin/env bash にする。この1行が無いと、拡張子が正しくても実行の方法が定まらない。

言語ごとの注意も公開されている。Python3で日本語などの文字を出す場合はシェバンを #!/usr/bin/env python3 の形にする必要があると書かれている。Node.jsの場合はシェバンに実行ファイルへの絶対パスを書く形が必要で、標準出力への書き込み方によっては表示されないという注意もある。Goを直接走らせる場合は、専用の書き方のシェバンを使い、コマンドがPATHに入っている必要があるとされている。

ターミナルで動くのにメニューバーで空になる

最も相談が多く、最も気づきにくいのがこれである。ターミナルで実行すれば正しい結果が出るのに、メニューバーでは何も出ない。原因はほぼPATHである。

ターミナルは起動時に利用者の設定ファイルを読み込むため、追加したコマンドの場所がPATHに入っている。一方、Finderやログイン時から起動されたアプリは、その設定ファイルを読み込まない。したがって、アプリから起動されたスクリプトのPATHは最小限の状態になり、追加で入れたコマンドが見つからない。

ドキュメントもこの点に触れており、スクリプトの中でPATHに追記する書き方を助言として示している。示されている例は、よく使われる場所を明示的に足す形である。ここで注意したいのは、Appleシリコンの環境ではパッケージ管理の既定の場所が別のディレクトリになっている点である。ドキュメントの別の箇所には、その場所を含む形のシェバンの例が載っている。手元の環境でどちらなのかは、ターミナルで対象のコマンドの場所を調べれば分かる。

対処は2つある。1つは、スクリプトの先頭でPATHに必要な場所を足すことである。もう1つは、コマンドを絶対パスで書くことである。後者は環境が変わったときに書き換えが要るが、確実である。

同じ理屈で、環境変数に依存する処理も止まる。ターミナルで設定していた認証情報などは、アプリから起動されたスクリプトには渡らない。値が必要な場合は、後述する変数の仕組みを使うほうが確実である。

出力の書式で行が消えている場合

実行はできているのに、思った行が出ない。この場合は書式の解釈を疑う。

区切り線の扱いが1つ目である。--- だけの行より下に書いた行は、ドロップダウンの中には出るがメニューバーには出ない、という仕様である。メニューバーに出したい行を区切り線より下に書いていないかを確かめる。

縦棒の扱いが2つ目である。縦棒より後ろは、その項目に対する指定として解釈される。色、文字の大きさ、フォント、リンク先、キーボードショートカット、表示する文字数の上限、前後の空白を削るかどうか、押せなくするかどうかなどが指定できる。出力する文字列の中にたまたま縦棒が含まれていると、そこから後ろが指定として読まれて消える。

3つ目は、複数行の扱いである。区切り線より上に複数の行を出すと、メニューバーの表示はその行を順番に切り替える動きになる。1行だけ出したいつもりで複数行を出していると、表示が入れ替わって見える。

4つ目は、色の記号の解釈である。ANSIの色指定を解釈する動きが既定で入っているため、色の記号をそのまま文字として出したい場合は解釈を切る指定が要る。文字数の上限を付けると、超えた分は省略記号になり、全文はマウスを重ねたときに出る。

値が更新されない、変数が反映されない

表示はされるが古い値のまま、という症状はここを見る。

更新の間隔はファイル名に書かれているため、間隔を変えたいときはファイル名を変えることになる。設定画面の中に間隔の項目を探しても見つからないのは、そういう作りだからである。

変数を使っている場合は、値の置き場所を知っておくと早い。プラグインが宣言した変数の値は、プラグインの隣に置かれるJSONのファイルに保存される。ファイル名はプラグインの名前に決まった接尾辞が付いた形である。公開されているドキュメントには、このファイルを直接書き換えてもよいこと、書き換えた後は更新の操作をして反映させることが書かれている。

更新の操作には、専用の書式のアドレスが用意されている。プラグインを1つだけ更新する形と、すべてを更新する形の両方がある。値を書き換える自動処理を作っている場合は、書き換えの後にこの更新をつなぐ。

本体の設定にも触れておく。自動更新の可否などは、アプリケーションサポートの下に置く設定ファイルで切り替えられる。このファイルは最初から存在するわけではなく、必要なら自分で作る。変更は次に起動したときから効き、ファイルを消して起動し直せば初期状態に戻る、という扱いになっている。おかしな挙動が続くときの切り分けとして覚えておくとよい。

1分で原因の層を絞る2つの実験

上から順に確かめる代わりに、原因がどの層にあるかを2つの実験で先に決める方法もある。

1つ目は、失敗しようのないプラグインを置いてみることである。名前を test.10s.sh にして、シェバンの行と日付を出す1行だけを書き、実行権限を付けて更新する。公開ドキュメントにも、最小のプラグインとしてこの形が例示されている。これが表示されれば、本体もフォルダもファイル名の規則も問題ないと分かるので、調べる対象は元のスクリプトだけに絞られる。表示されなければ、元のスクリプトを読むのは後回しでよい。読み込みの段階で止まっている。

2つ目は、アプリと同じ条件でスクリプトを走らせてみることである。普段のターミナルで実行しても、そこには利用者の設定で作られたPATHや環境変数が揃っているため、確かめたことにならない。環境変数を空にして実行する方法を使うと、アプリから起動された状態に近い条件になる。片方で成功して片方で失敗するなら、原因は環境への依存である。失敗したほうの出力に、見つからなかったコマンドの名前がそのまま出ることが多い。

エラーの出力先も押さえておきたい。プラグインのエラーは標準エラー出力へ送ることが求められている。途中で失敗したスクリプトでも、そこまでの出力は標準出力に出ているため、メニューには中途半端な内容が表示される。書式の問題に見えて実は途中で落ちていた、という取り違えはここで起きる。手で実行するときに標準エラー出力をファイルへ送っておけば、どちらなのかはすぐに分かる。

それでも直らないときと、直った後のこと

ここまでで直らない場合は、版の食い違いを疑う。配布元の最新の公開版とパッケージ管理が配っている版が同じとは限らない。手元の版がどちらなのかを確かめてから、既知の不具合の情報を探すほうが早い。必要なmacOSは10.15以降と記載されている。

権限の周りも見ておきたい。スクリプトが書類フォルダやデスクトップの中身を読む場合、macOSのプライバシーの設定で許可が要る。他のアプリを操作する処理を含む場合は、自動化の許可が別に要る。許可の要求は最初の1回しか出ないため、そこで拒否していると、以後は黙って失敗する。システム設定のプライバシーとセキュリティから、該当の項目を確認する。

不具合が直ると、次に来るのはメニューバーの幅の問題である。プラグインが3つ4つと増えると、常駐アプリのアイコンと合わせてメニューバーは横に伸びる。ノッチのあるMacBookでは、表示できる幅そのものが減っているため、押したい項目が隠れる状況が起きやすい。

対処の順番としては、まず出力の側を短くする。区切り線より下に置く、文字数の上限を付ける、常時見ない値はドロップダウンへ回す。それでも足りない分は、プラグイン以外のアイコンを整理する。クラウド保存や同期の常駐アプリは、設定でメニューバーへの表示を止められるものが多い。最後に残るのが、ときどき押すが常時は見なくてよい層である。この層は、隠したうえで必要なときだけ触れる形にすると幅が戻る。隠したアイコンを、メニューバーを畳んだまま押してその場でメニューを開ける作りであれば、隠したものへの到達が1手で済む。実装ごとの違いはほかの道具との違いに、機能の一覧はできることにまとめてある。導入して試すならダウンロードから入れる。