--bgと--printの競合エラーの解決法 — Claude Code
claude --bgに-pや--printを付けると出る競合エラーの理由と、バックグラウンド実行・非対話実行それぞれの正しいコマンドをまとめます。
--bgと--printは両立しない実行モードを指定している
claudeコマンドに--bgと-p(または--print)を同時に渡すと、セッションが始まる前に次のエラーで止まります。
--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.このエラーはClaude Code v2.1.198以降で出るようになったチェックです。--bgと--printが指している実行モードが根本的に矛盾しているため、Claude Codeはセッションを作る前にこの組み合わせを拒否します。
--bg(--background)はバックグラウンドセッションを開始し、後からclaude agentsで一覧に表示してアタッチする前提のモードです--print(-p)は非対話実行で結果を印字して終了するモードで、そもそもclaude agentsがアタッチしにいける対話セッションを開始しません
--bgは「後で戻ってこられるセッションを裏で立ち上げる」ためのフラグで、--printは「対話セッションを一切作らずに結果だけ返す」ためのフラグです。両方を指定すると、--bgが約束する「アタッチできるセッション」自体が存在しなくなるため、Claude Codeは矛盾を検知した時点でエラーにします。
対処 — どちらの結果が欲しいかで片方を外す
バックグラウンドで動かして後からアタッチしたい場合は、--printを外します。プロンプトは位置引数として渡すだけで完結します。
claude --bg "investigate the flaky SettingsChangeDetector test"実行するとセッションの短縮IDと管理コマンドが表示され、claude agentsを開けばそのセッションが一覧に並びます。あらかじめ定義したSub-agentをメインエージェントとして動かしたい場合は--agentを組み合わせます。
非対話実行で結果をその場で受け取りたい場合は、--bgを外して--printだけを使います。
claude -p "investigate the flaky SettingsChangeDetector test"CIパイプラインやスクリプトから呼び出す用途はこちらが該当します。バックグラウンドセッションの一覧に残す必要がなく、標準出力に結果が返ればよい場合は--bgを付ける理由がありません。
シェルコマンドを1つだけバックグラウンドジョブとして動かしたいだけなら、Claudeのセッションを介さず--execを--bgと組み合わせる選択肢もあります。
claude --bg --exec 'pytest -x'--nameでセッションを識別しやすくする
ヘッドレス運用でスクリプトから何本もclaude --bgを起動していると、claude agentsの一覧が自動生成された名前ばかりで見分けにくくなります。--nameを付けると表示名を自分で指定できます。
claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"実行直後の出力にも短縮IDと一緒に指定した名前が表示され、そのままclaude attachやclaude logsの引数に使えます。
backgrounded · 7c5dcf5d · flaky-test-fix
claude agents list sessions
claude attach 7c5dcf5d open in this terminal
claude logs 7c5dcf5d show recent output
claude stop 7c5dcf5d stop this session--agentで存在しないサブエージェント名を指定した場合はv2.1.191以降、--agent '<name>' not foundエラーでその場で起動が失敗するようになりました。それより前のバージョンでは、名前が一致しなくてもデフォルトのエージェントとして黙って起動していました。--bgは誤字や設定ミスをエラーで早期に検知する方向に、--agentも含めて段階的に整備されてきています。
バックグラウンドセッションを支えるスーパーバイザー
--bgで起動したセッションは、ターミナルを閉じても動き続けます。これは各セッションが独立したプロセスとしてではなく、スーパーバイザーと呼ばれる常駐プロセスの配下で動いているためです。スーパーバイザーはあらかじめ1つのワーカープロセスを起動待機させています。--bgやclaude agentsからの新規ディスパッチが来た瞬間、そのワーカーへディレクトリ・設定・資格情報を割り当てて動かし始めます。コールドスタートの遅延を避けるための仕組みで、割り当てた分の空き待機ワーカーはすぐに補充されます。
ヘッドレス運用で全てのバックグラウンドセッションを一括停止したい場合はclaude daemon stop --anyが使えます。--keep-workersを付けるとスーパーバイザー自体は止めつつ、個々のセッションは動かしたままにできます。次にclaude agentsかclaude --bgを実行したとき、新しいスーパーバイザーが既存のセッションへ再接続します。認証を環境変数(ANTHROPIC_API_KEY等)で行っている場合、次回の起動コマンドはその変数が設定されているシェルから実行する必要があります。
v2.1.198より前はエラーにならず、静かに壊れていた
このチェックが入る前のClaude Codeは、--bgと--printを同時に渡してもエラーにならず、実行だけは進んでいました。しかし結果はアタッチしようがないバックグラウンドジョブが黙って作られるというもので、claude agentsを開いても実質的に使えないセッションが残るだけでした。
| バージョン | --bg --printを渡したときの挙動 |
|---|---|
| v2.1.198より前 | --bg --printを渡したときの挙動エラーにならず実行される。アタッチ不可能なバックグラウンドジョブが黙って作られる |
| v2.1.198以降 | --bg --printを渡したときの挙動セッション開始前にエラーで停止。「--printを外して--bgだけにする」よう案内 |
つまり今エラーが出ているのは退行ではなく、以前は検出できなかった無意味な組み合わせが明示的に弾かれるようになった結果です。スクリプトやドキュメントにclaude --bg -p "..."のような書き方が残っている場合、それは動いているように見えて実際には何も回収できていなかった可能性があります。
スクリプトでハマりやすい2つのパターン
シェル関数やエイリアスで両方を暗黙に足してしまう。CIのラッパースクリプトで「非対話実行はこの関数を通す」というルールを作ったとします。バックグラウンド起動もその関数を経由してしまい、意図せず--printが付いた状態で--bgを呼んでいたというケースがあります。バックグラウンド起動用とワンショット実行用でラッパーを分けておくと事故を防げます。
claude -pのつもりで--bgの使用例をコピーしてしまう。ドキュメントやブログの--bgの例をコピーして、非対話実行がしたいだけなのに--bgごと持ってきてしまうパターンです。欲しいのが「即座に結果を受け取る」動作なら-p単体、「裏で走らせて後から確認する」動作なら--bg単体、と目的から逆算すると迷いません。
--forward-subagent-textなど--print前提のフラグと混同しない
--bg関連のオプションと、--printモード専用のフラグは別系統です。次の4つはいずれも--printが前提のフラグで、--bgとの併用は想定されていません。
--output-format stream-json--include-partial-messages--forward-subagent-text--json-schema
これらのフラグを使ったスクリプトに後から--bgを足そうとすると、同じ競合に当たります。バックグラウンドセッションの状態をスクリプトから読み取りたい場合は、--print系のフラグではなくclaude agents --jsonを使ってください。JSON配列での一覧取得はclaude agents --jsonでバックグラウンドセッションを操作するにまとめています。
運用の指針としては、--bgはディスパッチして戻ってくる前提の長めのタスク、--printは一度きりで完結する短いタスクという切り分けが基本になります。両方使いたくなったときは、まず「このジョブは終わったあと自分がアタッチして続きを見るか」を自問すると、どちらか一方に自然と決まります。
よくある質問
--bgと--printを両方使いたい状況自体が無いのですか
無いと考えて差し支えありません。--bgは「対話セッションを裏で維持してアタッチする」ためのフラグ、--printは「対話セッションを作らず即終了する」ためのフラグで、目的そのものが両立しません。両方欲しく感じる場合、実際には「非対話で実行しつつ進行状況だけ後から確認したい」という別の要求であることが多いです。その場合は--print --output-format stream-jsonで進行状況をストリーム出力する方法を検討してください。
--bg --execと--bg(プロンプトのみ)は何が違いますか
--bgだけの場合はClaudeのセッションがバックグラウンドで動き、プロンプトに対して自律的に作業します。--bg --execはClaudeのセッションを介さず、指定したシェルコマンドをPTY付きのバックグラウンドジョブとして直接実行します。テストコマンドの実行結果だけを裏で待ちたいような単純な用途では--execの方が軽量です。
エラーメッセージ通りに--printを外したのに、まだアタッチできません
claude --bgの直後は、まだバックグラウンドサービスの起動待ちでStarting background service…と表示されることがあります。この表示が出た場合は少し待ってからclaude agentsを開いてください。それでも一覧に出ない場合は、--cwdのパス指定が実行時のディレクトリと合っているか確認します。
エディタやIDEの拡張機能から--bgを呼んでいる場合も同じ制約ですか
はい、呼び出し元がシェル・スクリプト・エディタ拡張のどれであっても、claudeコマンド自体が--bgと--printの両方を検知した時点でこのチェックが働きます。拡張機能がバックグラウンド実行と非対話出力の両方を内部で組み立てているような設定になっていないか、渡しているコマンドライン引数を確認してください。
--bgと--dangerously-skip-permissionsを組み合わせるとどうなりますか
claude --bg --dangerously-skip-permissionsは、見ていないセッションが承認なしで操作できてしまいます。そのため対話セッションで一度claude --dangerously-skip-permissionsを実行し、ディスクレーマーに同意するまで拒否されます。同意済みであれば--bgと組み合わせて起動でき、その後スーパーバイザーがセッションを再起動してもモードは保持されます。--printとの競合エラーとは別のチェックなので、両方に引っかかっている場合は先に--printを外し、次に同意状況を確認する順番になります。
CIから起動したバックグラウンドジョブの出力だけ、あとでまとめて拾いたいです
--bg --execで起動したシェルコマンドの出力はディスクに書き込まれず、メモリ上に保持されて終了からおよそ5分で自動的に消えます。ログとして残したい場合は、コマンド側で結果をファイルにリダイレクトしておくか、終了直後にclaude logs <id>で回収してください。
claude agentsを一度も開いたことがなくても--bgは使えますか
使えます。claude --bgはワークスペースの信頼ダイアログへの同意を求めた後、必要であればバックグラウンドサービスを自動で起動してからセッションをディスパッチします。claude agentsを先に開いておく必要はなく、--bgから始めても後からclaude agentsで同じセッション一覧にたどり着けます。
まとめ
--bgと--printはどちらも「セッションの結果をどう受け取るか」を決めるフラグで、性質が正反対のため同時指定はできません。裏で動かして後からアタッチしたいなら--printを外してclaude --bg "<task>"にします。非対話でその場に結果が欲しいなら--bgを外してclaude -p "<task>"です。v2.1.198より前はこの組み合わせがエラーにならず黙って壊れていたため、古いスクリプトに残っていないか確認する価値があります。CLIフラグ絡みの他のエラーはClaude Codeでよくあるエラー10選でも扱っています。