0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Claude Code の attach と logs 入門、裏で動く作業を名前で開く

0
Posted at

はじめに

claude --bg で裏に回したセッションを見に行くとき、短い英数字の ID を一覧から拾ってコピーしているなら、その手間は v2.1.290 で減らせます。claude attach と claude logs が、ID の代わりにセッション名（の一部）を受け付けるようになったためです。ただし同じ「バックグラウンドセッションを扱うコマンド」でも、claude stop と claude rm は今も ID しか受け取りません。どのコマンドで名前が使えて、どこで ID が要るのかを、手順の流れに沿って整理します。

対象読者は、Claude Code を CLI で使っていて、長い作業を --bg で裏に回し始めた（または回したい）開発者です。

この記事で扱う範囲と検証の区別

記事の記述は 2 種類に分かれます。

区分 内容 根拠
実機で確認したもの v2.1.293 の --help 出力、存在しない ID を渡したときのエラーと終了コード、claude agents --json が空配列を返すこと、非 TTY での claude agents の挙動 2026-10-08 JST に npm から入れた v2.1.293 で実行した生出力
公式ドキュメントの記述 --bg で起動したセッションに実際に attach / logs する流れ、デタッチ操作、自動停止の条件など Agent view（公式ドキュメント）

検証環境は HOME を空ディレクトリに切り替えた未認証の状態で、作業ディレクトリも信頼済みではありません。そのため claude --bg は Workspace not trusted で止まり、セッションを実際に起動して attach する部分は確認できていません。その部分は公式ドキュメントの記述として紹介します。

TL;DR

この記事を読むと、次のことができるようになります。

  • claude --bg で起動したセッションの直近出力を claude logs "<名前の一部>" で確認する
  • claude attach "<名前の一部>" で同じセッションを手元の端末に開き、止めずに抜ける
  • 片付け（claude stop / claude rm）とスクリプト連携（claude agents --json）では ID を使い分ける

手順

全体の流れは次のとおりです。名前で指定できるのは「見る」側の 2 コマンドだけで、「止める・消す」側は ID のままという点が図の左右の差になっています。

1. バージョンを確認する

名前指定は v2.1.290 以降の機能です。2026-10-08 JST 時点の npm の dist-tags は次のとおりで、latest は 2.1.293、stable は 2.1.285 でした（npm: @anthropic-ai/claude-code）。

$ npm view @anthropic-ai/claude-code dist-tags --json
{ "stable": "2.1.285", "latest": "2.1.293", "next": "2.1.294" }

ここで読み落としやすいのは、npm の stable タグ（2026-10-08 JST 時点で 2.1.285）が v2.1.290 より前の版を指している点です。この版では名前指定は未対応のはずです（stable は動くタグなので、読む時点では進んでいる可能性があります）。手元のバージョンは claude --version で確認できます。

$ npm i @anthropic-ai/claude-code@2.1.293 ; claude --version
added 2 packages, and audited 3 packages in 7s
2.1.293 (Claude Code)

2. ヘルプでサブコマンドの引数を確認する

v2.1.293 の claude --help から、バックグラウンドセッション関連の部分だけを抜き出したものです。

  --bg, --background                    Start the session in the background and
                                        return immediately. Prints the id that
                                        `claude attach`, `logs`, `stop` and `rm`
                                        take; `claude agents` lists them. With
                                        --resume <session-id>, continues that
                                        session in the background under the same
                                        ID, or starts a copy and says so when
                                        the session is already running
Commands:
  agents [options]                      Manage background agents
  attach <id|name>                      Open a background session in this
                                        terminal. <id> is the short id that
                                        `claude --bg` prints and `claude agents`
                                        lists. Part of the session name works
                                        too
  logs <id|name>                        Print a background session's recent
                                        terminal output
  respawn [options] [id]                Restart a background session, or all of
                                        them with --all, so it runs the current
                                        Claude Code version
  rm <id>                               Delete a background session, and its
                                        worktree when that is safe. Works on
                                        sessions that have already exited
  stop|kill <id>                        Stop a background session. Its
                                        conversation is kept: `claude attach
                                        <id>` opens it again, `claude --resume`
                                        works once it is stopped

引数の表記に差があります。attach と logs は <id|name>、stop（別名 kill）と rm は <id> です。個別のヘルプにも同じ区別が出ており、名前に空白を含むときの書き方も添えられています。

$ claude attach --help
Usage: claude attach <id|name>

  Open the background session in this terminal. ← returns to agent view, Ctrl+Z drops back to your shell. The session keeps running either way. Part of the session name works in place of the id. Put a name with spaces in quotes.

$ claude logs --help
Usage: claude logs <id|name>

  Print the background session's recent terminal output. Part of the session name works in place of the id. Put a name with spaces in quotes.

$ claude stop --help
Usage: claude stop <id>

  Stop a background session. Its conversation is kept; resume it later with `claude attach <id>`.

筆者が v2.1.293 のヘルプを並べて確認した範囲では、名前（の部分一致）が通るのは表示・接続系の 2 コマンドだけでした。部分一致は複数のセッションに当たりうるため、取り消せない操作（停止・削除）には曖昧さのない ID を要求している設計と読めます。ただしこれはヘルプの表記からの推測で、公式に理由が書かれているわけではありません。

3. セッションをバックグラウンドで起動する

ここからは公式ドキュメントの記述です。Agent view のページ によると、--bg を付けるとセッションはすぐ裏に回り、プロンプトは位置引数で渡します。-p / --print との併用は拒否されます。ドキュメントに載っている起動例は次のとおりです。

claude --bg "investigate the flaky SettingsChangeDetector test"
claude --bg --name "flaky-test-fix" "..."
claude --resume <id> --bg "..."
claude --bg --exec 'pytest -x'

あとで名前で指定するつもりなら、--name を付けて起動しておくと探しやすくなります。起動直後には次のような出力が表示されると公式ドキュメントに例示されています（以下はドキュメントの例で、筆者の環境の出力ではありません）。

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

7c5dcf5d が ID、flaky-test-fix が名前です。ドキュメントによると、ID は ~/.claude/jobs/ 配下のディレクトリ名にあたります。

信頼済みでないディレクトリで --bg を実行すると、v2.1.293 では次のエラーで止まりました。一度そのディレクトリで claude を起動して信頼確認を承認してから再実行します。

$ claude --bg "say hi"
Workspace not trusted. Run `claude` in <dir> once and accept the trust prompt, then retry.

4. 一覧から ID と名前を拾う

起動中のセッションは claude agents で一覧できます。ただし対話端末が必要で、出力をパイプに流すような非 TTY の状況では次のメッセージで終わります。終了コードは 0 でした。

$ claude agents
'claude agents' requires an interactive terminal (stdout is not a TTY) — use 'claude agents --json' for a machine-readable listing.

スクリプトから使うなら --json です。ヘルプの説明は次のとおりで、TTY を必要としません。

  --cwd <path>   Show only background sessions started under <path>
  --json         Print active sessions (interactive and background) as a JSON array and exit (for scripting; does not require a TTY)
  --all          With --json: also include completed background sessions

セッションが 1 つもない未認証の環境では、空配列が返りました。

$ claude agents --json
[]

公式ドキュメントによると、--json の各要素は cwd / kind / startedAt / id / state / pid / status / waitingFor / sessionId / name を持ち、state は working / blocked / done / failed / stopped のいずれかです。ドキュメントは、スクリプトでは ~/.claude/jobs/ を直接パースせず claude agents --json を使うよう案内しています。終了済みのセッションも含めたいときは --all を足します。

claude agents 自体に --add-dir や --mcp-config を渡す場合は、agents の後ろに置く必要があります。前に置くと unknown option になると公式ドキュメントに注記があります。

5. claude logs で直近の出力を見る

claude logs は、セッションの直近のターミナル出力を表示するだけのコマンドです。attach と違って端末を占有しないので、「今どこまで進んだか」を確かめる用途に向いています。

v2.1.290 以降は、名前の一部でも指定できます。公式ドキュメントの例は次の形です。

claude logs "auth refactor"

公式ドキュメントには注意点が 1 つあります。--exec や ! で走らせたシェルジョブの出力はメモリ上にしか保持されず、コマンドの終了から約 5 分で消えます。テスト結果のように後から見返したい出力は、ファイルに書き出させておくほうが確実です。

6. claude attach で端末に開き、止めずに抜ける

claude attach は、バックグラウンドのセッションを手元の端末でフルインタラクティブに開きます。公式ドキュメントによると、表示は常にフルスクリーンで、離席中に何が起きたかの要約（recap）が表示されます。

claude attach "flaky-test-fix"

attach の扱いで迷いやすいのが抜け方です。公式ドキュメントでは、次の操作で抜けてもセッションは止まらないと説明されています。

  • 空のプロンプトで ←
  • /exit
  • Ctrl+Z
  • Ctrl+C または Ctrl+D を 2 回

v2.1.293 の claude attach --help には、← は agent view に戻り、Ctrl+Z はシェルに戻るという違いも書かれています（"← returns to agent view, Ctrl+Z drops back to your shell. The session keeps running either way."）。どちらで抜けても、セッションは動き続けます。attach 中にセッションそのものを止めたいときは /stop を使います。

7. stop / rm / respawn で片付ける

片付け系のコマンドは ID 指定です。役割の違いをヘルプと公式ドキュメントから整理すると次のようになります。

コマンド 受け付ける引数 何が残るか
claude stop <id>（kill） ID のみ 会話はディスクに残り、claude attach <id> で再開できる
claude rm <id> ID のみ 一覧から消える。transcript は claude --resume で引き続き使える
claude respawn <id> / --all ID または --all セッションを再起動し、現在の Claude Code バイナリで動かし直す

この表で押さえるのは、stop は一時停止に近く、rm も会話そのものは消さないという点です。完全に作業を捨てる操作ではありません。

rm には worktree（git の作業ツリー）に関するオプションがあります。ヘルプの抜粋は次のとおりです（行中の (...) は調査メモの時点での省略です）。

$ claude rm --help
Usage: claude rm <id> [--discard-unpushed <commit>@<worktree-id>] [--force-remove-worktree <worktree-id>]

  Delete a background session and its worktree. Unlike `stop`, works on already-exited sessions.
  --discard-unpushed <commit>@<worktree-id>  also discard the worktree's unpushed commits (and any uncommitted changes) while it is still the same worktree at that commit — pass the value a previous 'claude rm <id>' reported
  --force-remove-worktree <worktree-id>      delete the worktree directory even though the WorktreeRemove hook or git couldn't remove it (...) — pass the value a previous 'claude rm <id>' reported

公式ドキュメントによると、worktree に未コミットの変更が残っていると rm は worktree と一覧の行を残します。2 つのオプションはいずれも「直前の claude rm <id> が報告した値を渡す」形式なので、最初から付けて実行するものではなく、一度 rm を実行して報告を読んでから使う流れになります。

Claude Code を更新したあとは、動いているセッションが古いバイナリのままになります。claude respawn --all で全セッションを現行バージョンに切り替えられます。

$ claude respawn --help
Usage: claude respawn <id>|--all

  Restart a background session (or all of them) so it picks up the current Claude binary.

v2.1.290 で変わったこと

v2.1.290 で追加されたのは claude attach / claude logs というコマンドそのものではなく、「ID の代わりに名前の一部を渡せること」です。GitHub のリリースノートには次のように書かれています。

Added claude attach <name> and claude logs <name>: part of a session name works in place of the id
出典: Release v2.1.290 · anthropics/claude-code

同じリリースには、バックグラウンドセッション周りの修正も含まれています。

  • claude respawn が、保存済み transcript の無いセッションに過去のメッセージを再送してしまう不具合の修正
  • アイドルでバックグラウンド化したセッションが "no saved transcript" になる不具合の修正
  • claude agents から busy なバックグラウンドセッションへ送った /model /effort /rename が即時適用されるようになった

名前指定は「名前で探せること」が前提なので、起動時に --name を付けておく運用とセットで考えるのが自然です。なお attach / logs が最初に入ったバージョンは、今回確認した資料からは特定できていません。

トラブルシューティング

Q1: No job matching と表示される

存在しない ID や名前を渡すと、v2.1.293 では logs も attach も同じメッセージを出し、終了コード 1 で終わりました。

$ claude logs nonexistent
No job matching 'nonexistent'. Run 'claude agents' to list running sessions.
exit=1
$ claude attach nonexistent   (stdin=/dev/null)
No job matching 'nonexistent'. Run 'claude agents' to list running sessions.
exit=1

一方で、非 TTY の claude agents は案内メッセージを出して終了コード 0 で終わります。シェルスクリプトで「セッションがあるか」を判定するなら、claude agents の終了コードは当てにできません。claude agents --json の出力で判定するのが確実です（--json は interactive セッションも含むため、バックグラウンドだけを数えるなら kind が background のものに絞ります）。

Q2: attach が This session has no saved transcript で拒否される

公式ドキュメントによると、保存済みの transcript が無いセッションには attach できません。アイドル状態からバックグラウンド化したセッションがこの状態になる不具合は v2.1.290 で修正されているため、それより前のバージョンで起きている場合はまず更新してから確認し直します。

Q3: This conversation is already open in another running Claude session と表示される

公式ドキュメントでは、agent view の行についてこのメッセージが出る場合があると説明されています。たとえば別の端末で同じ会話を開いたままになっていないかを確認します。

Q4: しばらく放置したセッションが止まっている

公式ドキュメントによると、終了済みまたは入力待ちのまま約 1 時間 attach されていないセッションは、supervisor が停止します。Ctrl+T でピン留めしたセッションは対象外です。マシンをシャットダウンした場合も止まりますが、スリープには耐えます。

使う前に知っておきたい制約

公式ドキュメントの記述から、運用に影響するものを挙げます。

項目 内容
実行場所 セッションは自分のマシン上でのみ動く（クラウドに預けるものではない）
利用枠 セッションごとにサブスクリプション枠を消費する。10 並列ならおよそ 10 倍
隔離 git リポジトリでは .claude/worktrees/ に専用 worktree を作る（worktree.bgIsolation: "none" で無効）。git でないディレクトリではセッション間が隔離されない
無効化 設定 disableAgentView: true または環境変数 CLAUDE_CODE_DISABLE_AGENT_VIEW

利用枠の項目は見落とすと痛いところです。--bg は気軽に増やせる反面、10 本並べれば消費もおよそ 10 倍になると公式に明記されています。名前指定で「どれがどれか」を把握しやすくなったぶん、使っていないセッションを stop で止める習慣と組み合わせるのが無難です。

裏で動く常駐プロセス（daemon）の状態は claude daemon status|logs|stop --any で確認できます。セッションを起動していない v2.1.293 の環境では、claude daemon stop --any は no daemon running を返しました。

まとめ

冒頭の「どのコマンドで名前が使えるのか」への答えは、v2.1.293 のヘルプにそのまま出ています。

  • claude logs / claude attach は <id|name>。名前の一部でよく、空白を含む名前は引用符で囲む
  • claude stop / claude rm は <id> のみ。止める・消す操作では ID を確認してから実行する
  • スクリプトからは claude agents --json を使い、~/.claude/jobs/ はパースしない

日々の使い方に落とすと、起動時に --name を付け、様子見は claude logs "名前"、手を入れたいときは claude attach "名前" で入って ← で抜け、片付けだけ claude agents で ID を確認して stop / rm する、という分担になります。npm の stable タグ（2026-10-08 JST 時点で 2.1.285）の版を使っている場合は、名前指定が入る v2.1.290 以降に上がるまで ID 指定のままである点に注意してください。

関連記事

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?