MENU
  1. ホーム
  2. Claude Code
  3. Claude CodeのバックグラウンドBash – Ctrl+Bで長時間タスクを並走する

Claude CodeのバックグラウンドBash – Ctrl+Bで長時間タスクを並走する

Claude Code
Claude CodeのバックグラウンドBash - Ctrl+Bで長時間タスクを並走する | mohablog

Claude Code v2.1系の Background bash commands は、長時間動く npm run dev や pytest --watch を別タスクへ逃がす機能。本流の編集を止めずに走らせ続けるのが狙い。仕様の本筋は公式ドキュメント Interactive mode の “Background bash commands” セクションに収まっています。

目次

バックグラウンド実行で何が解決するのか

同期Bashだけで開発を回そうとすると、開発サーバーを起動した瞬間にClaudeとの会話が止まります。タスクが終わらない以上、次のプロンプトを投げられない。ターミナルを分割して別ウィンドウでサーバーを動かす運用もできますが、その場合はサーバーログをClaudeに見せる導線が断たれます。

同期Bashが詰まる典型ケース

Next.js プロジェクトでよくある流れを例に挙げます。

$ npm run dev

> next-app@0.1.0 dev
> next dev

  ▲ Next.js 15.2.0
  - Local:        http://localhost:3000

 ✓ Ready in 1.8s
# プロセスがフォアグラウンドに居座る。Claudeに次の指示が出せない

Ctrl+C で止めるまでBash tool が解放されません。Claudeから見れば「コマンド実行中」のまま。ファイル編集もテスト実行も次に進められない。

公式が想定している背景化対象

Interactive mode ドキュメントの “Common backgrounded commands” には、想定されるコマンド群が明記されています。

  • Build tools: webpack / vite / make
  • Package managers: npm / yarn / pnpm
  • Test runners: jest / pytest
  • Development servers
  • Long-running processes: docker / terraform

ビルド・テスト・サーバー・コンテナ。要するに「終了を待たずに進めたいもの全部」が対象です。

Ctrl+Bでバックグラウンドへ移す手順

フォアグラウンドで投げてからCtrl+B

手順自体は2ステップ。Claudeに普通にBashを投げさせて、走り始めたタイミングで Ctrl+B を押すだけ。

1. プロンプト: 「npm run dev を起動して」
2. Claude が Bash tool で npm run dev を呼ぶ
3. 起動メッセージが流れ始める
4. Ctrl+B を押す
→ background task ID が返り、Claude は次の指示を受け付ける状態に戻る

公式の “How backgrounding works” セクションには、こう書かれています。”When Claude Code runs a command in the background, it runs the command asynchronously and immediately returns a background task ID.”

背景化された瞬間にtask ID が発番され、本流の会話がブロックから解放される、というのが核心。

Tmux環境ではCtrl+Bを2回

Tmuxを噛ませている場合、Ctrl+B はTmux自身のprefixキーと衝突します。公式の表記は “Tmux users press twice”。同じキーを2回連打することでClaude Codeまで信号が届きます。

Shellモード(! プレフィックス)からの背景化

プロンプト先頭に ! を付けて直接シェルへ流すShellモードでも、同じ Ctrl+B が使えます。公式: “Supports the same Ctrl+B backgrounding for long-running commands.” Claudeを介さずに自分で打ったコマンドでも、同じキーで背景に回せる。

! pytest --watch tests/
[Shell mode] running: pytest --watch tests/
... テスト監視が走り続ける
→ Ctrl+B で背景化、Claude のプロンプトに戻る

出力ファイルからログを拾うパターン

背景化したコマンドの出力は、画面に流れるのではなくファイルに書き出されます。公式表記: “Output is written to a file and Claude can retrieve it using the Read tool.” Readでファイルを開けば必要部分だけClaudeのコンテキストへ載ります。

vite起動 → エラーが出たログだけ拾う

プロンプト:
  vite を起動してlocalhost:5173 が開けるまで監視して。
  エラーが出たら該当ログをコピーして原因を直して。

Claude の動き:
  1. Bash tool で `npm run dev` 起動
  2. Ctrl+B 相当で background task に移行(task ID=bg_abc123)
  3. 数秒待つ
  4. Read tool で出力ファイルを末尾50行だけ読む
  5. "TypeError: Cannot read properties of undefined" を検出
  6. 該当ファイルを修正、再起動

Readで毎回全文を読まず、末尾だけ抜き取るのがコンテキスト節約の鍵です。長時間動かしていればログは数MBに膨らみますが、関心があるのは直近のエラー行だけ、というケースが多い。

task ID は何に使うのか

公式は “Background tasks have unique IDs for tracking and output retrieval” と書いています。複数の背景タスクを同時に走らせたとき、どのIDがどのコマンドに対応するかをClaudeに伝えておけば、Readで指定先を間違えにくくなる。Webサーバーとtest watcherを並走させる構成では、ID単位で出力ファイルが分離されるため、片方のログだけ抜き出して読む操作がやりやすい。直近のエラー出力だけ200行読む、といったピンポイント操作で動かせます。

背景化したくなる典型コマンド

公式が挙げるカテゴリを、実プロジェクトでの使い分けに落とすと次の表になります。

カテゴリ具体コマンド例背景化する理由
開発サーバーnpm run dev / vite起動後ずっと張り付くため。HMR ログを拾いつつ編集を続ける
テストwatchpytest --watch / jest --watch変更検知ごとに再実行されるため、走らせっぱなしが前提
ビルドwebpack --watch / vite build --watch差分ビルドを背後で回し、ログでエラーだけ拾う
パッケージ取得npm install / pnpm install依存が多い場合は数分。完了通知を待つよりID で進捗確認
コンテナ/IaCdocker compose up / terraform apply長時間出力が続く。終わるまで本流の編集を止めない

逆に git status や ls のような瞬殺コマンドを背景化する意味はありません。背景化のコストはtask管理のオーバーヘッドのほうが大きい。

サブエージェント背景化との違い

「バックグラウンド」と聞いて混同しやすいのが、サブエージェントのバックグラウンド実行です。これは別物。Bashの背景化とサブエージェントの背景化は対象もキーバインドも分かれています。

キーバインドが違う

対象背景化停止
Bash tool で動くコマンドCtrl+B(Tmuxは2回)セッション終了で自動cleanup
サブエージェントTask tool 起動時に run_in_background: trueCtrl+X Ctrl+K を3秒以内に2回

Interactive mode の General controls 表には、サブエージェント側の停止が別キーバインドで明記されている。”Kill all running background subagents in this session. Press twice within 3 seconds to confirm.” Bash用の Ctrl+B とは別系統だと覚えておくと、後で「動かしっぱなしのサブエージェントが止められない」事故を避けられます。

使い分けの軸

処理がシェルコマンドで完結するなら Bash 背景化、Claudeの推論が要るならサブエージェント背景化。境界はそれだけです。pytestを走らせて結果を読むのは Bash 背景化で十分、別ファイル群の調査をさせて報告だけ受け取るならサブエージェント、という棲み分けになります。

5GBの自動終了とcleanup挙動

背景タスクは無制限に居座れるわけではありません。公式に明記された自動終了条件があります。

  • Claude Code終了時の自動cleanup: “Background tasks are automatically cleaned up when Claude Code exits.” セッションを閉じれば残骸は残らない
  • 出力5GB超過で自動終了: “Background tasks are automatically terminated if output exceeds 5GB, with a note in stderr explaining why.” stderr に終了理由が書き込まれるので、Readで末尾を拾えば原因が分かる

5GB は普通の開発サーバーログでは到達しません。ただ、stdout に大量のデバッグ出力を吐くスクリプトを背景化しっぱなしにすると到達します。例えば console.log ループを抱えたままのアプリを24時間以上動かしっぱなし、というのが典型の事故パターン。

注意したいのは、この5GB が 出力ファイル単体のしきい値という点。Claude Code 自体のディスク使用量とは別軸で計算されます。Web サーバーを背景化したくらいでは、HMR ログでも数十MB に収まるため、まず到達しません。問題になるのはデバッグ用の print や console.log をループ内で吐く構成。1回の自動化ジョブで気づかぬうちにGB単位を溜め込みます。

CLAUDE_CODE_DISABLE_BACKGROUND_TASKSで完全無効化

背景化機能そのものをオフにしたいケース向けに、環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS が用意されています。

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
claude
→ Ctrl+B を押しても背景化が走らない。
  Bash tool は同期実行のみになる。

公式の Environment variables ページから引用された記述: “To disable all background task functionality, set the CLAUDE_CODE_DISABLE_BACKGROUND_TASKS environment variable to 1.” 主な用途はCI環境やヘッドレス実行(claude -p)。意図せず背景タスクが残ってクリーンアップで詰まる、という事故を防ぐためのスイッチです。

誰がこの変数をセットすべきか

ローカル開発で対話的に使う分には、ほぼ常にオンのままで困りません。逆にGitHub ActionsやDockerコンテナの中で claude -p をワンショットで叩くなら、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を入れておくほうが副作用が読みやすい。背景タスクが残ったままジョブが終わる、という挙動を完全に潰せます。

まとめ

  • Background bash commands は Interactive mode の機能。同期Bashで詰まる長時間コマンドを別タスクへ逃がせる
  • 背景化は Ctrl+B 1回。Tmux環境のみ2回
  • 出力はファイルに書かれ、Readツールで部分的に読み戻せる
  • 出力5GB超過とClaude Code終了で自動cleanup。残骸は残らない
  • サブエージェント背景化は別系統。停止は Ctrl+X Ctrl+K を3秒以内2回
  • 完全無効化は CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1。CIやヘッドレス向け

背景化を覚えると、開発サーバーを別ウィンドウで動かす運用から離れられます。サーバーログをClaudeに直接読ませてエラー対処まで委ねられる、という導線の差は大きい。Tmuxで Claude Code を回している人は Ctrl+B 2回の仕様だけ忘れずに。

Claude Code
Claude Code デバッグ 自動化
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！
目次