Claude CodeのAlacritty設定がterminal-setupで食い違うときの直し方
terminal-setupがAlacrittyの設定を別のパスに新規作成し、既存のalacritty.tomlが効かなくなる報告があります。探索順の確認とShift+Enterの手動設定をまとめます。
/terminal-setupのあとにAlacrittyの色やフォントが戻ってしまう
Claude Codeの /terminal-setup を実行したら、Alacrittyの配色やフォントが初期状態に戻った。GitHubのissue #16066には、そうした報告があります。
報告者の環境はmacOSで、Claude Codeのバージョンは2.0.76でした。設定ファイルは ~/.alacritty.toml にあったのに、コマンドは ~/.config/alacritty/alacritty.toml を新しく作り、Shift+Returnのキーバインドだけを書き込んだといいます。Alacrittyは新しく作られたほうのファイルを読むので、元の設定が効かなくなります。
このissueはまだ解決していません。ラベルには bug と stale が付いたままで、修正バージョンの記載もありません。この記事は、同じ状況に当たったときに何を確かめ、どう手で直すかを扱います。/terminal-setup の一般的な手順と対応ターミナルの一覧は、terminal-setupコマンドでShift+Enterが効かないときの対処にあります。
Alacrittyが設定ファイルを探す場所と順番
Alacrittyは設定ファイルを自動では作りません。UNIX系では、次の5か所を順に探します。Alacrittyのマニュアルは、この順で並べています。
| 順 | パス | 備考 |
|---|---|---|
| 1 | パス$XDG_CONFIG_HOME/alacritty/alacritty.toml | 備考XDG_CONFIG_HOME を設定している環境向け |
| 2 | パス$XDG_CONFIG_HOME/alacritty.toml | 備考同上。ディレクトリを掘らない形 |
| 3 | パス$HOME/.config/alacritty/alacritty.toml | 備考XDG_CONFIG_HOME が未設定でもここは対象 |
| 4 | パス$HOME/.alacritty.toml | 備考ドットファイルとしてホームに置く形 |
| 5 | パス/etc/alacritty/alacritty.toml | 備考システム全体の設定 |
Windowsでは %APPDATA%\alacritty\alacritty.toml だけです。
issueが問題にしているのは、3と4の関係です。ホーム直下の .alacritty.toml(4)だけを使っている人のところへ、コマンドが3のパスにファイルを作ると、リストの上位にある3が読まれます。issue本文のコメントにも、新規ファイルが $HOME 直下の設定より優先されたことに驚いたという声があります。
なお、issueのタイトルは ~/alacritty.toml、本文は ~/.alacritty.toml と、ドットの有無が揺れています。Alacrittyのマニュアルにあるのは、ドット付きの $HOME/.alacritty.toml です。ドット無しの ~/alacritty.toml はリストにありません。
自分の環境が当てはまるか確かめる
次の3点が重なると、この症状が出る条件になります。
- Alacrittyのバージョンが0.16より前である
- 設定ファイルを
~/.alacritty.tomlなど、/terminal-setupの書き込み先以外に置いている /terminal-setupをまだ実行していない、または実行した直後で配色が変わった
1点目は、Claude Code側の仕様に関わります。ドキュメントでは、kitty keyboardプロトコルに対応した端末(foot、Alacritty 0.16以降)は設定なしでShift+Enterが動きます。ただしClaude Codeのv2.1.269以降が条件です。/terminal-setup が必要になるのは、0.16より前のAlacrittyです。つまり新しいAlacrittyとClaude Codeの組み合わせなら、この問題の入口になるコマンド自体を実行しなくて済みます。
alacritty --version
claude --versionどちらも先頭の数字が版です。Alacrittyが0.16以降、Claude Codeが2.1.269以降なら、まずShift+Enterを試してください。動くなら /terminal-setup は不要です。
0.16より前を使っている場合は、実行する前に設定ファイルがどこにあるかを見ます。
echo "XDG_CONFIG_HOME=${XDG_CONFIG_HOME:-未設定}"
ls -l "${XDG_CONFIG_HOME:-$HOME/.config}"/alacritty/alacritty.toml \
"${XDG_CONFIG_HOME:-$HOME/.config}"/alacritty.toml \
"$HOME/.alacritty.toml" 2>&1存在するファイルだけが ls に表示され、無いものは No such file or directory になります。見つかったものが ~/.alacritty.toml だけなら、/terminal-setup が別のパスに新しいファイルを作る可能性を疑う状況です。
実行前にバックアップを取る
issueの報告者は、コマンドの望ましい挙動として「既存のTOMLを解析してバインドを統合する」「.bak を作る」「上書き前に警告する」の3つを挙げています。現状でこの3つが揃っているという記載は、ドキュメントにはありません。Zedについては、バックアップを作って統合する挙動が書かれていますが、Alacrittyの項目に同じ説明はないのです。
そこで、実行前に自分で控えを取っておきます。
cp ~/.alacritty.toml ~/.alacritty.toml.bak/terminal-setup の実行後は、先ほどの ls をもう一度走らせます。ファイルが増えていたら、新しく作られたパスの中身を開き、キーバインドだけが入っているかを見ます。増えていなければ、既存のファイルに書き込まれたということです。
手動でShift+Enterを設定する
コマンドに任せない場合は、設定ファイルへ自分でバインドを足します。issueの報告で、コマンドが書き込んでいた内容は次の形です。
[[keyboard.bindings]]
key = "Return"
mods = "Shift"
chars = "\x1b\r"Shift+Returnを押すと、ESCとCRの2文字をターミナルに送る指定です。chars は、Alacrittyのマニュアルでは「指定した文字列をターミナルに書き込む」バインドと説明されています。
ただし、このまま貼ると2つの問題が起こりえます。
すでに[keyboard]がある場合は同じ配列に書く
issueのコメントに、すでに [keyboard] の bindings 配列を持っていた人が、[[keyboard.bindings]] を後から足されて重複キーのエラーになった例があります。同じ keyboard.bindings を、配列リテラルと配列テーブルの2通りで宣言するのは、TOMLとして両立しません。
既存の keyboard.bindings がある場合の書き分け
エラーになる形
[keyboard] の bindings = [ ... ] がある状態で、別に [[keyboard.bindings]] のブロックを足します。報告では、これで設定ファイルが読み込めなくなりました。
通る形
既存の bindings 配列の中に、1要素として追記します。次のコード例のように、カンマ区切りで並べます。
既存の配列に統合した例は次のとおりです(報告にあった SpawnNewInstance のバインドを残した形)。
[keyboard]
bindings = [
{ key = "N", mods = "Control|Shift", action = "SpawnNewInstance" },
{ key = "Return", mods = "Shift", chars = "\u001b\r" },
]エスケープは \u001bの形にする
もう1つの報告は、コマンドが書いた chars = "\x1b\r" を含む設定ファイルが「解析できない」というものです。画像付きの報告に対し、別のユーザーが \x を \u001b に書き換えたら直ったと返信しています。上の統合例が \u001b を使っているのは、このためです。
\x でエラーになる原因は、issueの中では議論されていません。同じ症状が出た人が2人いて、うち1人が \u001b で直した、という範囲が確認できる事実です。
設定を反映して確かめる
Alacrittyには general.live_config_reload という設定があり、既定では有効です。ファイルを保存すると自動で読み直されます。ただし、この設定を無効にしている場合や、構文エラーがある場合は反映されません。保存したら、新しいウィンドウを開いて確かめるのが安全です。
- Alacrittyを開き、
claudeを起動する - 入力欄に文字を打ち、Shift+Enterを押す
- 送信されず、入力欄の中で改行されれば成功
送信されてしまうなら、バインドが読まれていません。ファイルが別のパスにないか、ls で確かめ直してください。tmuxの中で動かしているときは、外側の端末が対応していてもShift+Enterは送信になります。tmuxの設定が別に要るため、terminal-setupの記事の該当箇所を見てください。
元に戻す・別のパスを消す
/terminal-setup が新規にファイルを作っていた場合、元の設定に戻す方法は2つあります。
新規作成されたファイルを片付ける手順
- 1
新規ファイルの中身を確認する
~/.config/alacritty/alacritty.tomlを開き、キーバインド以外が入っていないかを見ます。入っていなければ、元の設定はドットファイル側に残っているはずです。 - 2
Shift+Enterのバインドだけを控える
新規ファイルの
[[keyboard.bindings]]の4行を、既存の設定ファイルのkeyboard.bindings配列へ移します。書き方は前節のとおり、\u001bを使います。 - 3
新規ファイルを削除する
バインドを移し終えたら、新規ファイルを消します。リストの3番目が無くなるので、Alacrittyは4番目の
~/.alacritty.tomlを読みます。
XDG_CONFIG_HOME 側に移したい人は、逆にドットファイルの中身を $XDG_CONFIG_HOME/alacritty/alacritty.toml へ移す手もあります。issueのコメントにも、設定を $XDG_CONFIG_HOME に引っ越すつもりだという声があります。こちらなら、コマンドの書き込み先と置き場所が一致します。
Alacritty 0.16へ上げれば、そもそも書き込みが要らない
いちばん根本的な回避は、Alacrittyを0.16以降に上げ、Claude Codeをv2.1.269以降にそろえることです。kitty keyboardプロトコルで端末が自分のキー入力を伝えるため、設定ファイルにバインドを書く必要がなくなります。
Claude Codeのchangelogでは、v2.1.269で、kitty keyboardの問い合わせに答える端末(footやAlacritty 0.16以降)がShift+Enterを使えるようになったと記載されています。設定ファイルを触らずに済むぶん、この記事で扱った探索パスの食い違いも起こりません。
設定なしでShift+Enterが動く端末へ乗り換える手もあります。Ghosttyがその一つで、症状と設定はClaude CodeをGhosttyで使うときの設定と既知の症状にまとめています。
Alacrittyを上げられない事情があるなら、Shift+Enterを諦める方法もあります。Ctrl+J、または \ を入力してからEnterを押すと、どの端末でも設定なしで改行できます。
使い方の判断早見表
| 状況 | 取る手 |
|---|---|
| Alacritty 0.16以降、Claude Code v2.1.269以降 | 取る手何もしない。Shift+Enterを試す |
0.16未満で、設定が XDG_CONFIG_HOME 側にある | 取る手/terminal-setup の前に控えを取って実行 |
0.16未満で、設定が ~/.alacritty.toml | 取る手手動で追記する(実行しても別パスに作られる報告あり) |
すでに [keyboard] がある | 取る手既存の bindings 配列に1要素として足す |
| 設定が解析できないと言われる | 取る手\x1b を \u001b に直す |
| 設定に触りたくない | 取る手Ctrl+J、または \ +Enter |
まとめ
/terminal-setup は、Alacrittyの設定がホーム直下のドットファイルにある環境で、探索順の上位に別ファイルを作ったという報告があります。確認できるのは2.0.76での報告で、最新版の挙動はissueに書かれていません。実行する前にAlacrittyの版と設定ファイルの場所を調べ、控えを取り、必要なら手で追記するのが無難な運び方です。