CLAUDE_CODE_TASK_LIST_IDとは — タスクリストを複数セッションで共有する環境変数

CLAUDE_CODE_TASK_LIST_IDは、複数のClaude Codeインスタンスに同じIDを設定して、1つのタスクリストを共同で参照させる環境変数です。ターミナルを分けて同じプロジェクトを触っているとき、片方が作ったチェックリストをもう片方からも見られるようにします。対象になる「タスクリスト」の中身、設定コマンド、共有が効く条件と効かない条件をまとめます。

CLAUDE_CODE_TASK_LIST_IDが共有するタスクリストとは何か

ここで言うタスクリストは、Claudeが多段階の作業を計画するために自分で作るTodoチェックリストのことです。Ctrl+Tで表示・非表示を切り替えられ、保留・進行中・完了の状態が並びます。表示は一度に最大5件で、Claudeがまだ何も作っていないときはCtrl+Tを押しても見た目は変わりません。

このタスクリストは、/tasks(別名/bashes)で確認するバックグラウンド作業の一覧とは別物です。/tasksが見せるのはセッション内で動いているシェルやサブエージェントの状況で、CLAUDE_CODE_TASK_LIST_IDが対象にするのはClaude自身が立てた計画のチェックリストのほうです。名前が似ているため混同しやすい2つの機能ですが、共有できるのはあくまで後者です。Claudeが作業をサブエージェントに振った場合、その進捗は/tasks側に現れ、終わったサブエージェントも一覧に残ります。一方でタスクリストのチェックリスト項目は、サブエージェントへ委任したかどうかに関わらずClaude自身の計画として並びます。

タスクリストはコンテキストの圧縮(compaction)をまたいでも保持されます。--resumeや--continueでセッションに戻ったとき、タスクが残っていれば展開表示の状態も復元され、空であれば折りたたまれた状態で始まります。

想定される使い方はこうです。1人がターミナルAでClaude Codeに大きめの作業を任せ、Claudeが計画を立ててタスクを追加していきます。別のターミナルBで同じIDを指定して起動すれば、BのCtrl+Tにも同じ進捗が表示されます。Aで何が完了しどこが進行中かを、Bから見に行くたびに聞き直す必要がありません。

設定方法

同じIDを複数のClaude Codeインスタンスに渡すだけで、そのIDに紐づいた~/.claude/tasks/配下の名前付きディレクトリを共有するようになります。1つ目のターミナルで起動します。

CLAUDE_CODE_TASK_LIST_ID=my-project claude

別のターミナルでも同じ値を指定して起動すれば、そちらのセッションから同じタスクリストが見えます。値が1文字でも違うと別のディレクトリを参照するため共有されません。

毎回シェルで指定するのが面倒であれば、.claude/settings.jsonのenvキーに書いてプロジェクト単位で固定する方法もあります。

{
  "env": {
    "CLAUDE_CODE_TASK_LIST_ID": "my-project"
  }
}

IDの値そのものに特別な形式はなく、ディレクトリ名として使える文字列であれば衝突を避けて自由に決められます。プロジェクトごとに別のIDを割り当てれば、案件をまたいでタスクリストが混ざる心配もありません。

シェルで指定した場合は次にセッションを起動したときから有効になります。settings.jsonのenvキーに書いた場合は、ファイルを保存した時点で実行中のセッションにも反映されます。ただし一部の機能は起動時に読んだ値を保持し続けるため、設定を変えてもすぐには反映されないことがあります。反映されたかどうか不安なときは、一度セッションを立ち上げ直すのが確実です。

共有が効く条件と効かない条件

CLAUDE_CODE_TASK_LIST_IDが機能するのは、セッションにタスク管理ツール(TaskCreate・TaskGet・TaskUpdate・TaskList、または旧来のTodoWrite)が存在している場合に限られます。ツール自体が無いセッションでは、IDを設定してもタスクリストが生まれないため共有のしようがありません。

既定でタスク管理ツールが有効なモデル群とCLAUDE_CODE_ENABLE_TODO_TOOLSによるオプトインは、Claude Code v2.1.268以降の挙動です。それより前のバージョンでは対象モデルの範囲が異なる場合があります。

新しいモデルほどチェックリストを書かずに多段階作業を管理できるため、Claude Codeはそうしたモデルにタスク管理ツールを既定で付けません。ツール自体の定義文とリマインダーがコンテキストを消費するためです。裏を返すと、CLAUDE_CODE_TASK_LIST_IDで共有したい場面では、まずセッション側にタスク管理ツールがあるかどうかを先に確認する必要があります。

共有する2つのインスタンスが同じモデルである必要はありません。片方がタスク管理ツールを既定提供するモデル、もう片方がCLAUDE_CODE_ENABLE_TODO_TOOLS=1でオプトインした別モデルでも、双方にツールさえあれば同じIDで同じタスクリストを参照できます。IDが一致しているかどうかだけが条件で、モデルの組み合わせは問いません。

ツールを有効にする方法はCLAUDE_CODE_ENABLE_TODO_TOOLS=1だけではありません。起動コマンドの--allowedToolsや--toolsフラグにタスク管理ツールの名前を1つでも指定すると、それだけでそのセッションはタスク管理ツールにオプトインした扱いになります。環境変数を組織のポリシーで固定できない場合でも、起動コマンド側でオプトインする逃げ道があるということです。

モデルの制約を気にしなくてよいケースもあります。バックグラウンドセッションとClaude Code on the webは、使っているモデルの種類にかかわらず常にタスク管理ツールが有効です。両方の環境で動くセッション同士なら、モデルの対応状況を確認せずにCLAUDE_CODE_TASK_LIST_IDを使えます。

共有タスクリストを片付けるにはどうするか

プロジェクト単位のローカル状態をまとめて消すclaude project purgeは、対象にタスクリストも含みます。ただしこれは既定のプロジェクトスコープの保存先を指すコマンドです。CLAUDE_CODE_TASK_LIST_IDで名前を付けて共有しているディレクトリは、プロジェクトの場所とは別に~/.claude/tasks/配下にIDごとに存在するため、claude project purgeでは消えません。

rm -rf ~/.claude/tasks/my-project

共有をやめて元の個別セッションに戻したいだけなら、ディレクトリを消さずにCLAUDE_CODE_TASK_LIST_IDを未設定に戻すだけで十分です。ディレクトリを削除するのは、そのID用のタスクリストごと完全に片付けたいときに限ります。

エージェントチームでのタスク共有との違い

複数のClaudeを協調させる方法には、CLAUDE_CODE_TASK_LIST_IDによるインスタンス間共有のほかに、agent teamsのチームメイトが使う共有タスクリストもあります。両者は仕組みが異なります。

同一プロセス内で動く(in-process)チームメイトは、あなたのセッションが持つツールをそのまま引き継ぎます。セッションにタスク管理ツールがあれば、チームメイトも同じ共有タスクリストを介して連携できます。一方、split paneで独立したClaude Codeプロセスとして動くチームメイトは、そのプロセス自身のモデルでツールの有無が決まります。タスク管理ツールを持たないチームメイトは、共有タスクリストの代わりにメッセージのやり取りでチーム内の調整をします。

つまりCLAUDE_CODE_TASK_LIST_IDは「別々に起動した複数のClaude Codeインスタンス」を明示的なIDで束ねる仕組みで、agent teamsの共有タスクリストは「1つのチームというくくりの中」で自動的に働く仕組みです。

CIで複数の並列ジョブを同じタスクリストで見たい場合は、ジョブごとの起動コマンドに同じCLAUDE_CODE_TASK_LIST_IDを渡す構成が候補になります。

よくある質問

片方のセッションだけタスク管理ツールが無いとどうなるか

ツールが無いセッションは、多段階作業を計画してもタスクリストに何も追加しません。共有先のファイル自体を壊すことはなく、そのセッション側から書き込みが発生しないだけです。ツールがある側のセッションが作ったタスクは、通常どおりもう片方からも見えます。

まとめ

CLAUDE_CODE_TASK_LIST_IDは、Claudeが作るTodoチェックリストを複数のClaude Codeインスタンス間で共有する環境変数です。共有対象はCtrl+Tで開くタスクリストであり、/tasksが見せるバックグラウンドのシェル・サブエージェント一覧とは別物です。効果が出るのはセッションにタスク管理ツールがある場合に限られるため、対象モデルに含まれない環境では先にCLAUDE_CODE_ENABLE_TODO_TOOLS=1でツール自体を有効にしておく必要があります。この既定の対象モデル範囲はClaude Code v2.1.268以降のものなので、古いバージョンを使っている場合は挙動が異なることがあります。同じプロジェクトを複数ターミナルで並行して触るチームや、CIの並列ジョブで進捗を一箇所にまとめたい場合に使う変数です。並列実行そのものの上限を調整したい場合はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS、タスクリストの見方やCtrl+T操作の詳細はClaude Codeタスクリスト表示の見方とCtrl+T操作、サブエージェントのモデルを固定したい場合はCLAUDE_CODE_SUBAGENT_MODELにまとめています。