Claude Media
--bgと--printの競合エラーの解決法 — Claude Code

--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は、同時に成り立ちません。

v2.1.289で実際に出た挙動

空のホームディレクトリと空の設定ディレクトリに差し替えた一時ディレクトリでv2.1.289のclaudeに3通りの綴りを渡すと、次の結果になります。

claude --bg -p "x"
claude --background --print "x"
claude -p --bg "x"

3つとも、前節のメッセージを標準エラー出力に1回だけ出して終了コード1で止まります。標準出力は空で、短縮形と長い綴り、引数の順序のどれでも結果は同じでした。一時ディレクトリに増えたのは設定ディレクトリだけで、バックグラウンドセッションは作られていません。

つまり、スクリプトのset -eやCIのジョブは、このエラーをそのまま失敗として受け取れます。エラー文を標準出力のログから探しても見つからないので、標準エラー出力を残しているかを先に確かめます。--bgの位置が悪くて起動しない別のエラーはClaude Codeの--bgがflag or textと判定される原因にあります。

対処は目的に合わせて片方を外す

くらべる

どちらの結果が欲しいか

--print を外す

裏で動かしたい

後からclaude agentsで一覧を開き、アタッチしたり出力を読んだりしたい場合です。プロンプトは位置引数として渡します。

claude --bg "<task>"

--bg を外す

結果をその場で受け取りたい

CIパイプラインやスクリプトで、標準出力に結果が返ればよい場合です。バックグラウンドセッションの一覧に残す必要はありません。

claude -p "<task>"

claude --bg "investigate the flaky SettingsChangeDetector test"

実行するとセッションの短縮IDと管理コマンドが表示され、claude agentsを開けばそのセッションが一覧に並びます。あらかじめ定義したSub-agentをメインエージェントとして動かすときは--agentを組み合わせます。

claude --agent code-reviewer --bg "address review comments on PR 1234"

--bgはディレクトリの信頼ダイアログも先に確認します。未承認のディレクトリで実行すると、ダイアログが出て、承認後にセッションが始まります。拒否すればセッションは作られず、ダイアログを出せないスクリプトからの実行ではWorkspace not trustedエラーで終了します。

シェルコマンドだけを裏で動かす--exec

実行したいのがClaudeへの依頼ではなくシェルコマンド1つなら、--bgに--execを組み合わせる方法があります。

claude --bg --exec 'pytest -x'

コマンドはPTY付きのバックグラウンドジョブとして走り、モデルは呼ばれません。claude agentsの入力欄でも、先頭に!を付けてコマンドを続ければ、同じシェルジョブを起動できます。ジョブは一覧に1行で並び、その行には出力の最新の1行が状態として表示されます。出力はメモリ上に保持され、ディスクには書かれません。コマンドの終了からおよそ5分で行ごと自動的に消えます。結果を残したいときは、コマンド側でファイルにリダイレクトするか、終了直後にclaude logs <id>で読みます。

v2.1.289のclaude --helpの一覧には--execが出ません。公式のCLIリファレンスには載っているフラグなので、--helpだけを頼りにしていると見落とします。仕組みの詳細はClaude Codeの--execフラグガイドにあります。

--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

バックグラウンドサービスがまだ動いていないときは、この出力の上にStarting background service…が出ます。サービスの起動待ちなので、少し待ってからclaude agentsを開きます。一覧にセッションが出ないときは、claude agents --cwd <path>で絞り込む先のパスが、セッションを起動したディレクトリを含んでいるかを確かめてください。

--agentに存在しないサブエージェント名を渡すと、v2.1.191以降は--agent '<name>' not foundエラーでセッションがすぐ終了します。起動直後はbackgroundedと表示されることがあります。それより前は、名前が一致しなくても既定のエージェントとして黙って起動していました。

バックグラウンドセッションを支えるスーパーバイザー

--bgで起動したセッションは、ターミナルやclaude agentsを閉じても動き続けます。各セッションは独立したプロセスで、スーパーバイザーと呼ばれる常駐サービスの配下にあります。スーパーバイザーは、最初に--bgを実行するかclaude agentsを開いたときに自動で立ち上がります。

まとめ

セッションの状態とプロセスの扱い

  • 作業中・許可待ち・アタッチ中

    プロセスは動き続けます。実行中のサブエージェントやモニターも作業中に数えられます。

  • 終わった・返信待ちで約1時間放置

    リソース節約のためプロセスが止まります。会話はディスクに残り、次にアタッチするか返信すると続きから再開します。Ctrl+Tでピン留めすれば止まりません。

  • 予期せず終了

    スーパーバイザーが動いている間は、プロセスが再起動されます。←や/backgroundで自分でバックグラウンドにしたセッションをkillで止めた場合は、再起動ではなく停止扱いです。

  • 自動アップデートの後

    スーパーバイザーが新しいバージョンで自分自身を再起動し、アイドル状態のセッションを順に移します。作業中のセッションは中断されません。

全てのバックグラウンドセッションを止めたいときはclaude daemon stop --anyを使います。--keep-workersを付けるとスーパーバイザーだけを止め、個々のセッションは動かしたままにできます。次にclaude agentsかclaude --bgを実行すると、新しいスーパーバイザーが既存のセッションに再接続します。

認証を/loginではなくANTHROPIC_API_KEYなどの環境変数で行っている場合は、再起動後の最初のコマンドを、その変数が設定されたシェルから実行します。

v2.1.198より前は黙って壊れていた

このチェックが入る前は、--bgと--printを同時に渡してもエラーにならず、アタッチ不能なバックグラウンドジョブが黙って作られていました。

同じ流れで、v2.1.191では存在しない--agent名がエラーになり、v2.1.281では--bgが作業ディレクトリの信頼を先に確認するようになりました。

今エラーが出ているのは退行ではなく、以前は通っていた無意味な組み合わせが弾かれるようになった結果です。claude --bg -p "..."の形が古いスクリプトやドキュメントに残っていれば、動いているように見えて何も回収できていなかった可能性があります。

スクリプトでハマりやすい2つのパターン

シェル関数やエイリアスが--printを暗黙に足す。CIのラッパーで「非対話実行はこの関数を通す」と決めていると、バックグラウンド起動もその関数を経由し、--printが付いたまま--bgが呼ばれます。バックグラウンド起動用とワンショット実行用でラッパーを分けておけば防げます。

claude -pのつもりで--bgの例をコピーする。ブログや公式ページの--bgの例を、非対話実行がしたいだけなのに--bgごと持ってくる形です。欲しいのが即座に返る結果なら-pだけ、後から見に戻るジョブなら--bgだけ、と目的から逆算すると迷いません。

--print専用のフラグに--bgは足せない

--printでしか動かないフラグがあります。v2.1.289のclaude --helpには、次のように書かれています。

フラグ--helpの記述
--output-format--helpの記述Output format (only works with --print)
--input-format--helpの記述Input format (only works with --print)
--include-partial-messages--helpの記述only works with --print and --output-format=stream-json
--forward-subagent-text--helpの記述only works with --print and --output-format=stream-json

--json-schemaの説明文には--printの記載がありません。公式のCLIリファレンスは「print mode only」としています。いずれもスクリプトに後から--bgを足すと、同じ競合に当たります。

バックグラウンドセッションの状態をスクリプトから読むには、--print系のフラグではなくclaude agents --jsonを使います。JSON配列での一覧取得はclaude agents --jsonでバックグラウンドセッションを操作するにまとめています。完了済みも含めるなら--allを併用します。

--bgはディスパッチして戻る前提の長めのタスク、--printは一度で完結する短いタスクに向きます。迷ったら、終わった後に自分がアタッチして続きを見るかどうかで決まります。

よくある質問

--bg --dangerously-skip-permissionsは使えますか

見ていないセッションが承認なしで動けてしまうため、対話セッションで一度claude --dangerously-skip-permissionsを実行し、ディスクレーマーに同意するまで拒否されます。同意済みなら--bgと組み合わせられ、スーパーバイザーがセッションを再起動してもモードは保持されます。--printとの競合とは別のチェックなので、両方に当たるときは--printを外してから同意状況を確認します。

claude agentsを一度も開いていなくても--bgは使えますか

使えます。claude --bgは信頼ダイアログへの同意を求めたあと、必要ならバックグラウンドサービスを自動で起動してからセッションを渡します。先にclaude agentsを開く必要はなく、あとから同じ一覧にたどり着けます。

--bgのセッションは、いまのチェックアウトを直接書き換えますか

セッションは作業ディレクトリで始まりますが、ファイルを編集する前に、.claude/worktrees/以下の分離されたgit worktreeへ移ります。並列のセッションは同じチェックアウトを読めますが、書き込みはそれぞれのworktreeに向かいます。

まとめ

結果をその場で受け取るならclaude -p "<task>"、裏で動かして後から戻るならclaude --bg "<task>"と、目的で片方を選びます。古いスクリプトの点検は、grep -rn -e '--bg' . | grep -e ' -p ' -e '--print'のように、--bgと-pが同じ行に並ぶ箇所を拾えば足ります。CLIフラグまわりの他のエラーはClaude Codeでよくあるエラー10選でも扱っています。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/ja/errors
  2. code.claude.com/docs/ja/agent-view
  3. code.claude.com/docs/ja/cli-reference
  4. code.claude.com/docs/en/changelog
この記事を共有:XはてブLinkedIn