BASH_MAX_OUTPUT_LENGTHとは — Bash出力の切り詰めを調整する環境変数

BASH_MAX_OUTPUT_LENGTHは何を変える変数か

BASH_MAX_OUTPUT_LENGTHは、Bashコマンドを実行したあとClaude Codeが結果へ読み込む文字数を調整する環境変数です。既定値は30,000字、設定できる上限は150,000字です。ビルドログやテストスイートの出力が長く、必要な行が結果から漏れて見えなくなる場面で使います。

Claude Codeはコマンドの出力をまず作業用ファイルへストリーミングし、実行が終わってからそのファイルを読み戻します。BASH_MAX_OUTPUT_LENGTHが決めているのは、この読み戻しの窓の大きさです。既定の30,000字で足りない大きな出力を扱うときに、150,000字まで引き上げられます。

設定方法 — シェルとsettings.jsonの使い分け

その場限りで試すならシェルのexportで十分です。

export BASH_MAX_OUTPUT_LENGTH=100000
claude

恒久的に効かせたいならsettings.jsonのenvキーに書きます。個人の全プロジェクトに効かせるなら~/.claude/settings.json、チーム全員に効かせるならリポジトリの.claude/settings.jsonです。

{
  "env": {
    "BASH_MAX_OUTPUT_LENGTH": "100000"
  }
}

シェルとsettings.jsonの両方で同じ変数を設定した場合はsettings.json側が勝ちます。Claude Codeは起動時とファイル変更時にenvの値をプロセス環境へ書き込み、シェルから引き継いだ値を上書きするためです。CIのように実行のたびにシェル変数を渡す運用では、意図せずsettings.jsonの値に上書きされていないか一度確認しておくと安心です。

書き込む設定ファイルは、誰にどこまで効かせたいかで選びます。~/.claude/settings.jsonは自分だけに、しかも触るプロジェクトすべてに効きます。個人の作業スタイルとして常にログを多めに読ませたい場合はここに置きます。.claude/settings.jsonはリポジトリに含めてバージョン管理する前提のファイルで、そのプロジェクトで作業する全員に同じ値を配れます。CIのビルドログが長くなりがちなリポジトリなら、この形でチーム共有にするのが向いています。自分だけそのプロジェクトで値を変えたいなら.claude/settings.local.jsonを使います。Claude Codeが値を保存するときにgitignore済みの状態で書き出すファイルなので、手作業で作る場合は自分の.gitignoreにも追記しておきます。さらに上位には組織管理者が配布するmanaged設定があり、これが同じキーを指定していれば個人・プロジェクトどちらの設定よりも優先されます。

シーン別の目安値

用途によって必要な字数はかなり違います。値を大きくするほどコンテキストも消費するため、必要な範囲に絞るのが基本です。

150,000字を超える出力がどうしても必要な場合は、変数を上げるのではなくコマンド側で| tail -n 200のように絞り込む方が確実です。150,000字は公式ドキュメントが明記する「hard ceiling(絶対的な上限)」で、これを超えて指定しても意味がありません。

上げても変わらない30,000字の壁

ここが最も誤解されやすい点です。BASH_MAX_OUTPUT_LENGTHを引き上げても、コマンドが正常終了した場合(Valid)にClaude Codeへインラインで渡る文字数の上限そのものは変わりません。この上限はおよそ30,000字で固定されており、BASH_MAX_OUTPUT_LENGTHの値とは独立しています。

正常終了した結果が約30,000字を超えると、Claude Codeはインライン表示をあきらめ、セッションディレクトリに保存したファイルのパスと冒頭のプレビューだけを返します。Claudeは必要になったときにそのファイルを読み直したり検索したりします。BASH_MAX_OUTPUT_LENGTHを150,000まで上げても、この切り替えの境界(約30,000字)自体は動きません。変わるのは、読み戻しの窓が広がることで「必要になったときに読み直せる範囲」と「失敗時に頭と末尾を抜き出す元になる範囲」が広がる点です。

一方、コマンドが失敗扱い(Failure)になった場合は事情が異なります。Claude Codeが返すのはおよそ10,000字までの、読み戻し窓から切り出した先頭と末尾の抜粋です。ファイルパスは付きません。BASH_MAX_OUTPUT_LENGTHを上げると、この抜粋を切り出す元になる窓そのものが広がるため、出力の終盤で起きた失敗の手がかりが抜粋に含まれやすくなります。

なお、終了コード1が必ず失敗扱いになるわけではありません。grep・rg・find・diff・testやgit diff・git grepは、Claude Codeが「その状態は正常」と認識しているコマンドです。終了コード1でも正常終了(Valid)として扱われます。逆にpgrepが該当なしで終了コード1を返す場合やjq -eの判定失敗は、情報としては無害でも失敗(Failure)側の扱いになります。切り詰めの挙動を理解するときは、まずどちらの経路を通っているかを意識すると迷いにくくなります。

たとえばnpm run buildが45,000字のログを出しつつ正常終了したとします。このときClaude Codeが直接受け取るのは冒頭のプレビューとファイルパスだけで、ログ全体はセッションディレクトリのファイルに残ります。ビルドの警告が中盤に埋もれていても、Claudeがそのファイルを検索すれば見つけられる状態です。一方、同じログを吐きながらnpm run build自体が失敗で終わった場合は話が違います。返るのは先頭と末尾を合わせて1万字前後の抜粋だけで、警告がちょうど中盤にあると抜粋から漏れる可能性があります。BASH_MAX_OUTPUT_LENGTHを上げておくメリットが大きいのは、後者のように失敗時の手がかりが出力の途中に埋もれやすいコマンドです。

似た名前の変数と混同しない

Claude Codeには「出力の上限」を扱う環境変数が複数あり、名前が似ているため混同しやすいところです。それぞれ対象が別なので、目的に合わせて選びます。

BashコマンドのログやビルドツールのCLI出力が長すぎるときに触るのはBASH_MAX_OUTPUT_LENGTHだけです。Claude自身の応答が途中で切れる、あるいはMCPサーバーからの戻り値が大きいといった症状は別の変数の管轄になります。設定を変えたのに症状が直らないときは、まずどの経路の出力が切れているのかを切り分けると早く原因にたどり着けます。

似たタイムアウト系の変数としてBASH_DEFAULT_TIMEOUT_MSとBASH_MAX_TIMEOUT_MSもあります。こちらはコマンドが打ち切られるまでの時間を扱うもので、出力の文字数とは無関係です。長時間かかるコマンドが途中で強制終了される場合は、BASH_MAX_OUTPUT_LENGTHではなくこの2つを見直します。

この上限設計をどう読むか

既定値がインライン表示の境界とそろえて30,000字に置かれているのは、偶然というより理にかなった選択に見えます。エージェントが1回のツール呼び出しで抱え込む文脈は、コンテキストウィンドウという有限の資源を直接消費します。読み戻しの窓を無条件に広げてしまうと、必要のない出力までインラインで抱え込みやすくなり、かえって本題の情報が埋もれます。BASH_MAX_OUTPUT_LENGTHの既定は抑えめで、必要なときだけ明示的に広げる設計です。大量出力を狭く見積もっているというより、ほとんどのコマンド結果は数千字で要点が尽きるという実態に合わせた線引きだと考えられます。

この設計を踏まえると、変数を常に大きな値へ固定するのは得策ではありません。ふだんは既定値のまま運用し、ビルドやテストなど出力が長くなると分かっている作業の直前だけexportで引き上げる使い方のほうが実務には合います。プロジェクト全体に固定するなら、CIジョブのようにログが恒常的に長いリポジトリに限定するのが妥当です。

よくある質問

150,000字を超える値を設定するとどうなるか

hard ceilingという表現のとおり150,000字が実質的な上限です。CIのログがそれでも収まらない場合は、変数側でどうにかしようとせず、コマンド側でtailやgrepを挟んで必要な範囲だけを渡す方が確実です。

デフォルトの30,000字のままで困る場面はどのくらいあるか

シーン別の目安値で挙げたとおり、通常のコマンド実行では既定値のままで足ります。困りやすいのは、詳細ログ付きのビルドやフルテストスイートのように、出力そのものが数万字を超える作業です。作業内容ごとに一時的に値を切り替える運用が現実的です。

値を上げてもClaudeの応答が長く見えないのはなぜか

BASH_MAX_OUTPUT_LENGTHが広げるのはあくまでコマンド結果の読み戻し窓であり、Claude自身がユーザーへ返す応答の長さとは別の話です。応答側の出力トークンを調整したい場合はCLAUDE_CODE_MAX_OUTPUT_TOKENSを見ます。両者は名前が似ていても対象が違うため、症状に応じて使い分けが必要です。

まとめ

BASH_MAX_OUTPUT_LENGTHはBashコマンドの読み戻し窓を既定30,000字から最大150,000字まで広げる環境変数です。ビルドログやテストスイートの出力で必要な情報が漏れると感じたときに引き上げます。ただし正常終了時の約30,000字というインライン表示の境界自体は動かず、上げた分は「あとから読み直せる範囲」と「失敗時の抜粋の元になる範囲」を広げる形で効きます。同じ「MAX」を含むCLAUDE_CODE_MAX_OUTPUT_TOKENSやMAX_THINKING_TOKENSとは対象が別なので、症状に応じて変数を切り分けて設定するのが近道です。

環境変数を横断で見比べたい場合はClaude Code環境変数リファレンス、設定ファイルの書き方全般はClaude Code設定ガイドにまとめています。大きな出力そのものよりコンテキストの消費を抑えたい場合はContext exceeds token limitの意味と対処も参考になります。