Cross-Session Collaboration with Claude Code Tasks

Introduction

You're deep into a coding session. Claude Code has created a task list with twelve items. You've knocked out eight of them. It's late, you need to stop, but the work isn't done. Tomorrow, you start a new session and... the task list is gone. You're starting from scratch, trying to remember what was done and what remained.

This is the context loss problem that plagues every Claude Code user. Each session exists in isolation. The tasks you create, the progress you make, the context you build, all of it disappears when the session ends. Your next session starts fresh, with no memory of what came before.

But there's a solution most users don't know about: shared task lists. By setting a single environment variable, you can make task lists persist across sessions. Multiple terminal windows can see the same tasks. Progress made in one session appears instantly in another. The task list becomes a living document that survives session boundaries.

This article shows you exactly how cross-session task sharing works, how to set it up, and how to use it effectively in your development workflow.

How Task Storage Works

Understanding where Claude Code stores tasks helps you understand how cross-session sharing becomes possible.

The Default Storage Location

When you use Claude Code's task features, the tasks are stored locally on your machine. The default location is:

~/.claude/tasks/{sessionId}/

Each session gets its own unique session ID, and its tasks are stored in a corresponding directory. This isolation is intentional; it prevents sessions from interfering with each other. But it also means each session is a silo, unable to see or interact with tasks from other sessions.

Session Isolation by Default

When you launch Claude Code normally, it generates a new session ID. This session ID determines where tasks are stored and retrieved from. Two terminal windows running Claude Code will have different session IDs, different task directories, and completely separate task lists.

Terminal 1: claude
  -> Session ID: abc123
  -> Tasks stored in: ~/.claude/tasks/abc123/
  -> Creates task: "Implement user auth"

Terminal 2: claude
  -> Session ID: xyz789
  -> Tasks stored in: ~/.claude/tasks/xyz789/
  -> Cannot see "Implement user auth" task
  -> Completely isolated from Terminal 1

This isolation is fine for simple use cases. But when you want continuity across sessions, or when you want multiple terminals to coordinate on the same work, isolation becomes a limitation.

The Shared List Alternative

Here's the key insight: the session ID that determines task storage can be overridden. Instead of letting Claude Code generate a random session ID, you can specify your own. When multiple sessions use the same ID, they share the same task storage location, and therefore the same task list.

This is the foundation of cross-session collaboration. Same ID equals same tasks.

Using CLAUDE_CODE_TASK_LIST_ID

The CLAUDE_CODE_TASK_LIST_ID environment variable is how you override the default session isolation. Set it before launching Claude Code, and all sessions with the same value will share tasks.

Basic Usage

The simplest way to use it is inline when launching Claude Code:

CLAUDE_CODE_TASK_LIST_ID=myproject claude

This launches Claude Code with the task list ID set to "myproject". Any other session launched with the same ID will see the same tasks.

Persistent Configuration

For ongoing projects, you might want the ID set automatically. Add it to your shell profile:

# Project-specific task list
export CLAUDE_CODE_TASK_LIST_ID=myproject

Or create project-specific aliases:

# Different task lists for different projects
alias claude-webapp='CLAUDE_CODE_TASK_LIST_ID=webapp claude'
alias claude-api='CLAUDE_CODE_TASK_LIST_ID=api-server claude'
alias claude-mobile='CLAUDE_CODE_TASK_LIST_ID=mobile-app claude'

Choosing Good IDs

Your task list ID can be any string. Choose something meaningful that you'll remember:

# By project name
CLAUDE_CODE_TASK_LIST_ID=acme-dashboard

# By feature being built
CLAUDE_CODE_TASK_LIST_ID=user-authentication

# By date for time-boxed work
CLAUDE_CODE_TASK_LIST_ID=sprint-2024-01-15

# By purpose
CLAUDE_CODE_TASK_LIST_ID=bug-fixes
CLAUDE_CODE_TASK_LIST_ID=refactoring

Real-Time Broadcasting

The shared task list isn't just storage; it's live. When one session updates tasks, other sessions with the same ID see the changes in real time.

How Broadcasting Works

Claude Code monitors the task storage directory for changes. When a task is created, updated, or completed in one session, the change is written to the shared storage. Other sessions detect the change and update their view of the task list.

Terminal 1:                          Terminal 2:
CLAUDE_CODE_TASK_LIST_ID=proj claude  CLAUDE_CODE_TASK_LIST_ID=proj claude

> Create task: Fix login bug          (watching for changes...)
Task created: Fix login bug
                                      New task detected: Fix login bug

> Mark task complete                  (watching for changes...)
Task completed: Fix login bug
                                      Task updated: Fix login bug (complete)

No Manual Sync Required

You don't need to refresh, reload, or manually sync. The task list updates automatically. This makes it possible to have multiple terminals working in coordination, each aware of what the others are doing.

One terminal could be running tests while another is implementing features. Both see the same task list. When the implementation terminal marks a task complete, the testing terminal knows that feature is ready for testing.

Enabling Parallel Work

Real-time broadcasting transforms how you can work with Claude Code. Instead of one session doing everything sequentially, you can have specialized sessions working in parallel:

Terminal 1 (Planning):
- Creates tasks based on requirements
- Prioritizes and organizes work
- Monitors overall progress

Terminal 2 (Implementation):
- Picks up tasks from the shared list
- Marks tasks complete as it finishes
- Adds new tasks if issues discovered

Terminal 3 (Testing):
- Watches for completed implementation tasks
- Runs tests on completed features
- Creates bug tasks if issues found

Practical Workflows

Understanding the mechanism is one thing. Using it effectively is another. Here are practical workflows that leverage cross-session task sharing.

Morning/Evening Continuity

The most common use case: maintaining continuity across time. Start work in the morning, create a task list, make progress. End your session when you need to stop. Later, resume exactly where you left off.

$ CLAUDE_CODE_TASK_LIST_ID=dashboard-feature claude

> Let's build a user dashboard. Create tasks for:
> - Set up dashboard route
> - Create dashboard layout component
> - Add user stats widget
> - Add recent activity widget
> - Add quick actions panel

Tasks created. Starting work...
(completes first two tasks)

> I need to stop for now. What's our status?
Completed: Dashboard route, Layout component
Remaining: Stats widget, Activity widget, Quick actions

$ exit

$ CLAUDE_CODE_TASK_LIST_ID=dashboard-feature claude

> Show me the current task list

Current tasks:
[x] Set up dashboard route
[x] Create dashboard layout component
[ ] Add user stats widget
[ ] Add recent activity widget
[ ] Add quick actions panel

> Let's continue with the stats widget...

Multiple Terminals, One Project

When working on a complex feature, you might want multiple terminals open, each focused on a different aspect, but all coordinating through the same task list:

# Terminal 1: Frontend work
$ CLAUDE_CODE_TASK_LIST_ID=auth-feature claude
> Focus on frontend auth components

# Terminal 2: Backend work
$ CLAUDE_CODE_TASK_LIST_ID=auth-feature claude
> Focus on backend auth endpoints

# Terminal 3: Test writing
$ CLAUDE_CODE_TASK_LIST_ID=auth-feature claude
> Write tests for auth features as they're completed

Each terminal sees the same task list. When the frontend terminal marks "Login form component" complete, the test terminal knows to write tests for it. When the backend terminal completes "Auth endpoint," the frontend terminal knows the API is ready to integrate.

Handoff Between Sessions

Sometimes you need to hand off work to a different context, perhaps a different project directory or a fresh start with different instructions. The shared task list provides continuity even when the sessions are otherwise independent.

# Session 1: Create and plan
$ cd ~/projects/frontend
$ CLAUDE_CODE_TASK_LIST_ID=api-integration claude
> Create tasks for integrating the new payment API
(creates detailed task list, exits)

# Session 2: Different directory, same tasks
$ cd ~/projects/backend
$ CLAUDE_CODE_TASK_LIST_ID=api-integration claude
> Show me the task list
(sees all tasks from Session 1)
> Let's start with the backend tasks...

Works with claude -p and SDK

Cross-session task sharing isn't limited to interactive Claude Code sessions. It works with headless mode and the Agent SDK, opening up automation possibilities.

Headless Mode with -p

When using Claude Code's headless mode (-p flag for prompt), you can still access shared task lists:

# Create tasks from a script
$ CLAUDE_CODE_TASK_LIST_ID=nightly-build claude -p "Create tasks for the nightly build process"

# Check task status programmatically
$ CLAUDE_CODE_TASK_LIST_ID=nightly-build claude -p "Show incomplete tasks as JSON"

# Complete tasks from CI/CD
$ CLAUDE_CODE_TASK_LIST_ID=nightly-build claude -p "Mark the 'Run tests' task as complete"

Integration with Agent SDK

If you're building automation with the Claude Code Agent SDK, the task list ID can be set programmatically:

// Set the environment variable before spawning Claude Code
process.env.CLAUDE_CODE_TASK_LIST_ID = 'automated-workflow';

// Or pass it to the spawn configuration
const agent = spawn('claude', [], {
  env: {
    ...process.env,
    CLAUDE_CODE_TASK_LIST_ID: 'automated-workflow'
  }
});

Automation Possibilities

The combination of shared task lists and programmatic access enables sophisticated workflows:

# CI Pipeline creates tasks
on_pr_opened:
  CLAUDE_CODE_TASK_LIST_ID=$PR_NUMBER claude -p "
    Create tasks for PR review:
    - Check code style
    - Run test suite
    - Verify documentation
    - Check for security issues
  "

# Automated checks update task status
on_lint_complete:
  CLAUDE_CODE_TASK_LIST_ID=$PR_NUMBER claude -p "Mark 'Check code style' complete"

on_tests_pass:
  CLAUDE_CODE_TASK_LIST_ID=$PR_NUMBER claude -p "Mark 'Run test suite' complete"

# Human reviewer sees live status
$ CLAUDE_CODE_TASK_LIST_ID=pr-123 claude
> Show me the review checklist
(sees real-time status of automated checks)

Best Practices

To get the most out of cross-session task sharing, follow these practices.

Naming Your Task List IDs

Good naming makes task lists easy to manage and remember:

# Good: Descriptive, scoped, memorable
CLAUDE_CODE_TASK_LIST_ID=webapp-auth-feature
CLAUDE_CODE_TASK_LIST_ID=api-v2-migration
CLAUDE_CODE_TASK_LIST_ID=bugfix-session-2024-01

# Bad: Generic, confusing, hard to remember
CLAUDE_CODE_TASK_LIST_ID=tasks
CLAUDE_CODE_TASK_LIST_ID=work
CLAUDE_CODE_TASK_LIST_ID=123

When to Use Shared vs Separate Lists

Not every session needs a shared task list. Use this decision guide:

USE SHARED TASK LIST when:
- Work spans multiple sessions over time
- Multiple terminals need coordination
- You want to resume exactly where you left off
- You're building automation around tasks

USE SEPARATE (DEFAULT) LISTS when:
- Work is self-contained to one session
- No need for continuity after session ends
- Experimenting or exploring (not production work)
- You want complete isolation from other work

Cleaning Up Old Task Lists

Over time, you'll accumulate task lists for completed projects. Periodically clean up:

# View existing task list directories
$ ls ~/.claude/tasks/

# Remove old, completed project lists
$ rm -rf ~/.claude/tasks/old-project-name

# Or archive them
$ mv ~/.claude/tasks/completed-feature ~/archives/

Combining with COORDINATION.md

For complex projects, use shared task lists in combination with a COORDINATION.md file. The task list handles immediate, actionable items. COORDINATION.md handles broader context, phase tracking, and documentation that Claude Code should reference.

# Task list: Immediate actionable items
- [ ] Implement login endpoint
- [ ] Add password validation
- [ ] Create session tokens

# COORDINATION.md: Broader context
## Current Phase: Authentication (Phase 2 of 5)
## Decisions Made:
- Using JWT for session tokens
- Password requirements: 8+ chars, 1 number, 1 special
## Next Phase: Dashboard UI

Going Further

Cross-session task sharing solves the immediate problem of context loss between sessions. But it's just one piece of the coordination puzzle.

Tasks Are Coordination, Not Architecture

A shared task list tells you what to do. It doesn't tell Claude Code how to do it. It doesn't enforce naming conventions. It doesn't ensure consistency across files. It doesn't prevent Claude from making architectural decisions that contradict your patterns.

For a quick bug fix or small feature, task sharing might be all you need. But for serious projects, you need more than just shared tasks. You need shared understanding of how the project should be built.

The Limits of Environment Variables

Setting CLAUDE_CODE_TASK_LIST_ID is simple. But it requires remembering to set it. It requires consistent naming. It requires everyone working on a project to use the same ID. One typo creates a new, isolated task list.

For personal projects, this is manageable. For teams or complex projects, the manual coordination becomes error-prone. You need systems that don't rely on remembering to set environment variables.

Structured Teams Work Better

Cross-session tasks let multiple Claude Code instances share a to-do list. But what if those instances had defined roles? What if a "planning" instance created tasks that an "implementation" instance automatically picked up? What if a "review" instance validated work before marking it complete?

This is the difference between shared tasks and structured coordination. Tasks are a list. Structured coordination is a workflow. Claude Architect provides this structure, turning ad-hoc task sharing into a coordinated multi-agent system.