--exec（エグゼク）

Claude Codeで長く走るコマンド（テストやビルド）を裏で回したい人向け

テストやビルドのように、終わるまで何分もかかるコマンドを、Claude Codeの背景でこっそり走らせるための起動時の指定が --exec です。Claudeに何かを頼むのではなく、私たちがふだん黒い画面に打ち込むコマンドそのものを、裏でずっと回しっぱなしにできます。

注意したいのは、この指定が単独では動かないところ。必ず --bg という「背景で動かす」指定とセットで打ちます。

噛み砕くと、洗濯機のスタートボタンみたいなもの

洗濯機を回している間、私たちは横で立ったまま見張りませんよね。スイッチを押したら別の部屋で家事をして、ピーと鳴ったら戻ってくる。--exec はあれと同じ発想です。

時間のかかるコマンドにスタートを切らせて、自分はすぐ別の作業に戻る。Claude Code側には「○○というジョブが裏で走っています」という1行が残るだけで、終わったらその場所を見に行けば結果が分かります。Claudeに考えさせる用途ではない、というのがいちばんの肝です。

大事な前提：これは新しめの機能で、しかも単独では動かない

この機能が乗っているのは「agent view（背景セッション一覧画面）」という、走らせ中の裏作業を一覧で見る画面です。ここがまだ研究プレビュー段階。公式も次のように、今後変わる可能性があると明記しています。

Agent view is in research preview and requires Claude Code v2.1.139 or later. Check your version with claude --version. The interface and keyboard shortcuts may change as the feature evolves.

つまり Claude Code が v2.1.139 以上でないと、この一覧画面そのものが使えません。手元の番号は claude --version で確認できます。

そしてもう1つ。--exec は単独では使えません。公式の説明も「Use with --bg to launch from the shell」と書いていて、必ず --bg とセットで打つ前提です。

「料理ブログの全ページ生成を裏で回す」を例に手順を見る

題材は料理ブログのサイトです。レシピが何百個もあって、全ページをHTMLに組み立てる生成（ビルド）コマンドが、毎回3〜4分かかるとします。この待ち時間を別作業にあてたい、という場面で --exec が効きます。

ステップ1: まず手元のバージョンを確かめる

前提の v2.1.139 を満たしているか先に見ます。これを飛ばすと、後でジョブ一覧画面が開かなくて詰まります。

$ claude --version

返ってきた番号が v2.1.139 以上ならOK。古ければ先に新しくしておきます。

ステップ2: 生成コマンドを裏で走らせる

料理ブログの全ページ生成コマンドが npm run build だとします。これを背景ジョブとして投げる形がこれです。

$ claude --bg --exec 'npm run build'

--bg が「背景で動かして、すぐ手元を返してね」の指定。--exec の後ろの引用符の中身が、実際に走らせたいコマンドそのものです。公式が載せている形だと、こうなります。

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

どちらも構造は同じ。--exec の後ろを自分の用事に差し替えるだけです。

ステップ3: すぐ手元が返ってくる

投げた瞬間、画面には短いID（そのジョブの整理番号）と、後で操作するための命令一覧が印字されます。ここがポイントで、生成が終わるのを待たずに、もう次の作業に移れます。

私はこの「投げて即戻る」感覚が、最初けっこう不思議でした。

ステップ4: 待ち時間に別作業をする

生成が裏で3分回っている間、私たちは普通に別の窓でレシピ文章を直したり、画像を差し替えたりできます。裏のジョブは、見ていなくても勝手に進みます。

ここで初心者がやりがちな勘違いを1つ。「裏で走らせたんだから、終わったらClaudeが結果を読んで教えてくれるはず」と思いがちですが、それは起きません。--exec はClaudeを一切呼ばないので、生成のログを解釈する相手がいないんです。

ステップ5: 走り具合・結果を見に行く

一覧画面 claude agents を開くと、さっきのジョブが1行で並んでいて、いちばん新しい出力の1行がそのまま状態として見えます。中身をしっかり読みたいときは、ステップ3で出たIDを使ってこう打ちます。

$ claude logs <id>

これでそのジョブの最近の出力が表示されます。一覧画面の中なら、その行に入る（アタッチ）か、Space でちらっと覗くこともできます。

ステップ6: 終わった結果は早めに読む（消えるので）

ここが地味に大事です。このジョブの出力はディスクに保存されません。公式の言い方だと、コマンドが終わってから約5分でその行も出力も自動で片付きます。だから「生成が成功したか/エラーが出たか」を確かめたいなら、終わったあと放置せず、5分以内に claude logs <id> で読むのが安全です。

必要なら、生成コマンド側で結果をファイルに書き出しておくのが確実。

つまり --exec は何をしてくれるのか

• やってくれる: テストやビルドのような時間のかかるコマンドを、Claude Codeの裏で走らせて、すぐ手元を返す。終わった後は claude logs で結果を読める
• やってくれない: 走らせたコマンドの結果をClaudeが読んで解析・要約すること。--exec はClaudeを呼ばないので、出力は誰にも渡らない
• 意味が薄い場面: 1〜2秒で終わる短いコマンド。裏に回すありがたみがなく、普通に黒い画面で打った方が早い

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 料理ブログの全ページ生成を回しながら原稿を直す

レシピ300本のサイトで、全ページ生成に毎回3〜4分かかる。これを claude --bg --exec 'npm run build' で裏に投げて、待ち時間に新しいレシピの文章を書く。生成が終わったら claude logs <id> で「エラーなく全ページ出たか」だけ確認します。私はこの「待ち時間ゼロ運用」が地味にいちばん効くと思っています。

シナリオ2: 重いテストを裏で流して、その間に別の修正を進める

家計簿アプリを作っていて、全部のテストを通すのに5分かかるとします。公式そのままの形 claude --bg --exec 'pytest -x' で裏に投げ、待っている間に画面まわりの細かい直しを進める。テストが落ちたかどうかは、終わってから5分以内に出力を読みに行きます。

シナリオ3: 取り込んだばかりの公開プロジェクトで、初回の重い処理を裏に逃がす

GitHubから取ってきたばかりの公開プロジェクトは、最初の準備処理（必要なものの一括取り込みなど）がやたら重いことがあります。これを --bg --exec で裏に回しておけば、自分はその間に中身を読み進められる。終わったら一覧画面で結果の1行を見て、問題なさそうか判断します。

初心者が踏みやすい落とし穴

• Claudeは一切出てこない。公式も「no model is invoked and the output is not sent to any session」と明言。AIに結果を読ませたいなら、--exec ではなく普通の claude --bg "..." でClaudeセッションを立てる方を使います
• 出力は約5分で消える。ディスクに残らず、コマンド終了の約5分後に行ごと片付きます。残したい結果はコマンド側でファイルに書き出すか、終わったらすぐ claude logs <id> で読む
• 単独では動かない。--exec だけ打っても始まりません。必ず claude --bg --exec '...' の形にする
• 一覧画面の入力欄で「!」を打つのと中身は同じ。agent view の入力欄に ! npm run build のように頭へ「!」を付けて打つのと、--exec は同じジョブを起動します。どちらか好きな方でOK
• 「!」を付け忘れると別物になる。一覧画面の入力欄で「!」なしに文章を打つと、それはコマンド実行ではなくClaudeへの依頼になります。コマンドを走らせたいときは頭の「!」を忘れない
• /background や --bg 単独と混同しやすい。--bg 単独は「Claudeセッションを裏で立てる」、いま開いている会話を裏へ引っ越すのはまた別。--exec だけが「Claudeなしのコマンド実行ジョブ」です
• 研究プレビュー段階だと忘れない。一覧画面まわりは v2.1.139 以上が要るうえ、操作方法が今後変わる可能性があります。動かないときはまずバージョンを疑う

書き方

claude --bg --exec '走らせたいコマンド'

やってみるとこうなる

入力

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

出力例

投げた瞬間に手元が返り、そのジョブの短いID（整理番号）と、後で操作するための命令一覧が印字される。claude agents の一覧画面にそのジョブが1行で並び、いちばん新しい出力の1行が状態として見える。中身は claude logs ＜ID＞ で読めるが、出力は保存されず、コマンド終了の約5分後に行ごと自動で片付く。

関連項目

• --bg（ビージー）
• /background（バックグラウンド）
• /stop（ストップ）
• /agents（エージェンツ）

公式ドキュメント

https://code.claude.com/docs/en/agent-view