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側に現れ、終わったサブエージェントも一覧に残ります。サブエージェントがタスク管理ツールを使えるのは、親のセッションにそのツールがあるときだけです。サブエージェントが別のモデルで動いていても同じです。

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

使い方の流れは次の3段階です。

設定方法

同じ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"
  }
}

.claude/settings.jsonのようにリポジトリで共有する設定ファイルのenv値は、多くの場合、チームメンバーがそのフォルダーを信頼したあとに適用されます。

IDはそのまま~/.claude/tasks/配下のディレクトリ名になるので、プロジェクトごとに別のIDを割り当てれば、案件をまたいでタスクリストが混ざる心配もありません。

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

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

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

この対象範囲は、2回のリリースで今の形になりました。

このため、古いバージョンのClaude Codeを使うセッションが混ざる構成では、共有できる範囲が揃わないことがあります。

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

共有する2つのインスタンスが同じモデルである必要はありません。片方がタスク管理ツールを既定提供するモデル、もう片方がCLAUDE_CODE_ENABLE_TODO_TOOLS=1でオプトインした別モデルという組み合わせです。IDを揃えたうえで双方のセッションにツールがあれば、モデルが違っても共有できます。

ツールを有効にする方法はCLAUDE_CODE_ENABLE_TODO_TOOLS=1だけではありません。起動コマンドの--allowedToolsでタスク管理ツールを名指しする方法もあります(例: claude --allowedTools TaskCreate)。--toolsに並べる方法もありますが、こちらは組み込みツールを指定したものだけに絞ります。使い続けたい他の組み込みツールも一緒に並べてください。環境変数を固定できない環境では、起動コマンド側でオプトインできます。

v2.1.287のclaude --helpでは、2つのフラグは次のように表示されます。

claude --help

  --allowedTools, --allowed-tools <tools...>
      Comma or space-separated list of tool names to allow (e.g. "Bash(git *)
      Edit")
  --tools <tools...>                    Specify the list of available tools from
                                        the built-in set. Use "" to disable all
                                        tools, "default" to use all tools, or
                                        specify tool names (e.g.
                                        "Bash,Edit,Read").

--toolsは「組み込みツールの集合から使うものを指定する」フラグで、--allowedToolsは許可するツール名の一覧です。名指しした時点でタスク管理ツールが有効になる点は、どちらも同じです。Agent SDKのallowedToolsとtoolsオプションも、この2つのフラグと同じように働きます。

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

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

プロジェクトのローカル状態をまとめて消すコマンドの削除対象には、「セッション単位のtasks/」が入っています。このコマンドはv2.1.287ではclaude project purgeで、v2.1.288からはclaude purgeに名前が変わりました。--dry-runを付けると、消さずに削除計画だけを出せます。

claude project purge --help

Usage: claude project purge [options] [path]
 
Delete all Claude Code state for a project (transcripts, tasks, file history,
config entry)
 
Options:
  --all              Purge state for every project (mutually exclusive with
                     [path])
  --dry-run          List what would be deleted without deleting anything
  -h, --help         Display help for command
  -i, --interactive  Prompt for each item before deleting
  -y, --yes          Skip confirmation prompt

claude purgeの説明は「セッション単位のtasks/」としか書かれておらず、CLAUDE_CODE_TASK_LIST_IDで名前を付けたディレクトリが入るかどうかは分かりません。--dry-runの出力に~/.claude/tasks/配下の該当ディレクトリが出るかどうかで判断できます。出てこなければ、ディレクトリを直接消します。

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

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

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

複数のClaudeを協調させる方法には、CLAUDE_CODE_TASK_LIST_IDによるインスタンス間共有のほかに、agent teamsのチームメイトが使う共有タスクリストもあります。保存先は~/.claude/tasks/{team-name}/で、CLAUDE_CODE_TASK_LIST_IDと同じtasks/配下ですが、ディレクトリ名はチーム名で決まります。ローカルに残り、再開したセッションにも引き継がれます。保持期間は、セッションの記録と同じcleanupPeriodDaysの設定に従います。

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

まとめ

IDを揃えても、タスク管理ツールを持たないセッションは共有に参加できません。新しいモデルで足りないときはCLAUDE_CODE_ENABLE_TODO_TOOLS=1か--allowedToolsで補えます。

並列実行の上限を調整したい場合はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS、Ctrl+Tの操作の詳細はClaude Codeタスクリスト表示の見方とCtrl+T操作、サブエージェントのモデルを固定したい場合はCLAUDE_CODE_SUBAGENT_MODELにあります。