Claude Codeの--bgがflag or textと判定され起動しない原因
claude --bgの位置が悪いと「Couldn't tell whether --bg is a flag or text」と出て、何も始まらないまま終了コード1で終わります。警告文の読み方と正しい書き方をまとめました。
claude に --bg を付けたのに何も起動せず、次の一行だけが表示されて終了する。これが「Couldn't tell whether --bg is a flag or text」です。
Couldn't tell whether --bg is a flag or text here, so nothing was started. To start a background session put it first: claude --bg <prompt>原因は --bg を置いた位置です。Claude Codeが「バックグラウンド起動のフラグ」なのか「プロンプトの一部の文字列」なのかを判別できず、セッションを1つも作らずに終了コード1で止まります。直し方は警告文の末尾にあるとおり、--bg を先頭に置いて実行し直すだけです。
エラーが出たときに起きていること
公式のエラー一覧によると、このメッセージは --bg または --background を、フラグともテキストとも判別できない位置に置いたときに出ます。コマンドは何も開始せず、この1行を表示して終了コード1で終わります。
押さえておきたい点は3つです。
- セッションは作られていない。
claude agentsの一覧にも行は増えません - 終了コードは1。シェルスクリプトや
&&でつないだ処理は、ここで止まります --backgroundと書いた場合は、メッセージ中の名前も--backgroundになる
「失敗したのに何か動いているのでは」と探す必要はありません。何も始まっていないので、後始末なしでやり直せます。
このエラーの要点
- 警告文の案内は「
--bgを先頭に置く」 - 起動はゼロ件、終了コードは1
- 直し方は
claude --bg "<プロンプト>"の形に書き直すこと
正しい書き方 — プロンプトは位置引数にする
バックグラウンドセッションを始める基本形は、--bg の後ろにプロンプトを位置引数として置く書き方です。公式のagent viewのページでは、次の形が最初に示されています。
claude --bg "investigate the flaky SettingsChangeDetector test"表示名を付けたいときは --name を足します。エラー一覧の対処例も、同じ並びです。
claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"成功すると、短いIDと管理用のコマンドが表示されます。公式ページに載っている出力例は次のとおりです。
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… が出ることもあります。
先頭に置くしかないのか
警告文は「put it first」と案内しています。一方、公式の別の例には、--bg が先頭ではない書き方が載っています。
claude --agent code-reviewer --bg "address review comments on PR 1234"
claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"どちらも --agent や --resume のような値を取るフラグが前にあり、その後ろに --bg、最後にプロンプトが続きます。つまり、公式がサンプルとして示す形は次の2つに整理できます。
| 形 | 例 | 公式での扱い |
|---|---|---|
--bg が先頭 | 例claude --bg "<prompt>" | 公式での扱い基本形・警告文の案内 |
--bg の前に別のフラグ | 例claude --agent X --bg "<prompt>" | 公式での扱い使い方の例として記載 |
プロンプトの後ろに --bg | 例claude "<prompt>" --bg | 公式での扱い記載なし |
エラーになる位置の条件そのものは、公式のエラー一覧にもagent viewのページにも詳しい記載がありません。そのため、確実に通したいときは次の順で書くのが無難です。
- 先頭に
--bg --nameや--modelなどのオプション- 最後に引用符で囲んだプロンプト
プロンプトの後ろに --bg を足す書き方は、公式のサンプルに無い並びです。先頭に置けば、この並びの判定で迷う余地はなくなります。
前のコマンドに後から --bgを足したときの落とし穴
このエラーに当たりやすいのは、普通に動いていた対話用のコマンドを履歴から呼び出して、末尾に --bg を足す場面です。
末尾に足した次の形は、警告文が想定している並びから外れています。
claude "テスト失敗の原因を調べて" --bg先頭に移すと、警告文の案内どおりの形になります。
claude --bg "テスト失敗の原因を調べて"履歴の末尾に追記する癖があるなら、プロンプトを変数に入れて、先頭にフラグを置く小さなシェル関数にしておく方法もあります。次の関数は、読者のシェル設定に書き足すための一例です。
# ~/.zshrc などに追加する例
cbg() {
local name="$1"; shift
claude --bg --name "$name" "$*"
}
# 使い方
cbg nightly-audit "依存パッケージの脆弱性を洗い出して"この関数では、名前とプロンプトを渡す順序が固定されます。--bg が必ず先頭に来るので、位置を間違える余地がありません。
似たエラーとの見分け方
--bg まわりのエラーは複数あり、メッセージも対処も違います。取り違えると別の原因を探すことになるので、表で切り分けておきます。
| 画面の表示 | 原因 | 直し方 |
|---|---|---|
Couldn't tell whether --bg is a flag or text here, so nothing was started. | 原因--bg の位置が判別できない | 直し方claude --bg "<prompt>" の形にする |
--bg and --print conflict: ... | 原因--bg を -p や --print と同時に指定した | 直し方-p を外し、プロンプトは位置引数にする |
Workspace not trusted. | 原因信頼していないディレクトリで、確認ダイアログを出せない環境から起動した | 直し方そのディレクトリで一度 claude を実行して信頼を承認する |
--agent '<name>' not found | 原因--agent に存在しないサブエージェント名を渡した。no agent named の警告のあと backgrounded と表示されるが、セッションは即終了する | 直し方サブエージェント名を確認する。backgrounded の表示だけでは成功と判断しない |
-p との競合は別のエラーで、原因がまったく違います。詳しい経緯は--bgと--printの競合エラーの解決法にまとめています。今回のエラーは「位置」の問題で、-p を付けていなくても出ます。
信頼ダイアログについては、ターミナルから実行した場合はダイアログが先に表示され、承認するとセッションが始まります。辞退すると、セッションを作らずに終了します。スクリプトのようにダイアログを出せない場面でだけ、上の表の Workspace not trusted. が返ります。
起動したあとの確認
警告が消えて backgrounded · <ID> · <名前> が出たら、あとは通常のagent viewの操作です。一覧は claude agents で見られ、短いIDを使って claude attach や claude logs、claude stop で個別に操作できます。一覧の見方や状態の読み方はClaude Codeのagent viewで扱っています。
起動後に、バックグラウンドセッションが possibly low memory で始まらないときは、位置の問題ではなくメモリ不足です。こちらはagent viewのpossibly low memoryで原因を説明しています。
バックグラウンドセッションの権限モードは、claude --bg で起動した場合、同じディレクトリで新しい claude を開いたときと同じ決まり方になります。--permission-mode を足したいときの書き方はClaude Codeの--permission-modeで起動モードを指定するを参照してください。フラグを足すときも、--bg を先頭に置く原則は変わりません。
--agentで起動したセッションが再開されるとき
--agent で指定したサブエージェントは、バックグラウンドセッションが後から再開・再起動されたときにも復元され、ツールの制限も維持されます。復元ではセッション自身のディレクトリが先に探されます。そのワークスペースを信頼済みなら、プロジェクト単位のエージェントも別のディレクトリから再開して読み込めます。
エージェントがその後に削除されていた場合、セッションは既定のツールで続き、会話の冒頭にエージェント名を示す警告が出ます。起動できたのに挙動が変わったと感じたら、定義ファイルが消えていないかを確かめてください。
既存の会話を --resumeと --bgで続ける
--bg を --resume と組み合わせると、過去の会話をバックグラウンドで続けられます。完全なセッションIDを渡す形が基本です。
claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "続きから移行作業を仕上げて"v2.1.257以降では、同じIDのまま続行するか、新しいIDでコピーを作り、理由を note: 行で表示します。同じIDで続行できたときは、claude agents の行も1つのままです。
一方、--continue、値なしの --resume、名前やファイルパスを渡した --resume と --bg を組み合わせると、必ずコピーが作られます。意図してコピーを作るなら --fork-session を足せば、note: は出ません。コピーが増えて一覧に同じ話題の行が並ぶ場合は、この組み合わせが原因かもしれません。
起動したセッションはどこで編集するか
--bg で始めたセッションは、最初は今いるディレクトリで動き、ファイルを編集する前に .claude/worktrees/ 配下の独立したgit worktreeへ移ります。並列に走らせたセッション同士が、同じファイルを書き合わないための仕組みです。
次の場合は、worktreeへ移らずにその場で編集します。
- すでにリンクされたgit worktreeの中で起動した
- gitリポジトリではなく、
WorktreeCreateフックも設定していない - 編集先が作業ディレクトリの外にある
worktreeが扱いにくいリポジトリでは、プロジェクトの .claude/settings.json に次の設定を書くと、作業コピーを直接編集する動作に切り替わります。
{
"worktree": {
"bgIsolation": "none"
}
}gitリポジトリの外では、並列のセッションが同じファイルを編集すると互いに上書きしうるので、対象を分けて起動するのが安全です。worktreeの場所は、セッションにattachして作業ディレクトリを見ると分かります。
起動時の設定は引き継がれる
元の起動で渡した設定系のフラグは、バックグラウンド側にも引き継がれます。--mcp-config、--strict-mcp-config、--settings、--setting-sources、--add-dir、--plugin-dir、--fallback-model、--allow-dangerously-skip-permissions が対象です。/add-dir で途中から足したディレクトリも持ち越されます。
この引き継ぎは、開いていた対話セッションを /bg や ← でバックグラウンドへ送る場面の説明です。MCPサーバーや設定ファイルを指定して起動した対話セッションでも、バックグラウンドに送った後で設定が外れることはありません。
シェルコマンドをバックグラウンドで走らせる場合
--bg には、Claudeではなくシェルコマンドをバックグラウンドジョブとして走らせる --exec という組み合わせもあります。
claude --bg --exec 'pytest -x'この場合もやはり --bg が先頭です。ジョブはPTY付きで動き、agent viewに1行として現れます。モデルは呼び出されないため、出力がどこかのセッションに渡ることはありません。出力はメモリ上に残るだけで、ディスクには書かれません。コマンドが終わって約5分たつと、行も出力も自動で片付くので、結果が必要なら先に読み出しておきます。
まとめ
このエラーは「--bg の置き場所」だけが原因で、権限や環境の問題ではありません。セッションは作られず、終了コードは1です。警告文の案内どおり claude --bg --name "<名前>" "<プロンプト>" の形に書き直せば、その場で解消します。
自動化の中でコマンドを組み立てている場合は、--bg を固定の先頭として、可変のプロンプトを最後の引用符つき引数に置く構造にしておくと、再発しにくくなります。